@ckeditor/ckeditor5-ui 48.2.0 → 48.3.0-alpha.1

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 (117) hide show
  1. package/dist/arialiveannouncer.d.ts +90 -90
  2. package/dist/augmentation.d.ts +86 -86
  3. package/dist/autocomplete/autocompleteview.d.ts +70 -70
  4. package/dist/badge/badge.d.ts +119 -121
  5. package/dist/bindings/addkeyboardhandlingforgrid.d.ts +22 -22
  6. package/dist/bindings/clickoutsidehandler.d.ts +25 -25
  7. package/dist/bindings/csstransitiondisablermixin.d.ts +47 -36
  8. package/dist/bindings/draggableviewmixin.d.ts +45 -37
  9. package/dist/bindings/preventdefault.d.ts +30 -30
  10. package/dist/bindings/submithandler.d.ts +49 -49
  11. package/dist/button/button.d.ts +167 -167
  12. package/dist/button/buttonlabel.d.ts +28 -28
  13. package/dist/button/buttonlabelview.d.ts +26 -26
  14. package/dist/button/buttonview.d.ts +192 -192
  15. package/dist/button/filedialogbuttonview.d.ts +107 -99
  16. package/dist/button/listitembuttonview.d.ts +73 -73
  17. package/dist/button/switchbuttonview.d.ts +40 -40
  18. package/dist/collapsible/collapsibleview.d.ts +63 -63
  19. package/dist/colorgrid/colorgridview.d.ts +117 -117
  20. package/dist/colorgrid/colortileview.d.ts +21 -21
  21. package/dist/colorgrid/utils.d.ts +35 -35
  22. package/dist/colorpicker/colorpickerview.d.ts +155 -157
  23. package/dist/colorpicker/utils.d.ts +37 -37
  24. package/dist/colorselector/colorgridsfragmentview.d.ts +191 -191
  25. package/dist/colorselector/colorpickerfragmentview.d.ts +129 -129
  26. package/dist/colorselector/colorselectorview.d.ts +227 -229
  27. package/dist/colorselector/documentcolorcollection.d.ts +52 -59
  28. package/dist/componentfactory.d.ts +76 -76
  29. package/dist/dialog/dialog.d.ts +311 -288
  30. package/dist/dialog/dialogactionsview.d.ts +62 -62
  31. package/dist/dialog/dialogcontentview.d.ts +22 -22
  32. package/dist/dialog/dialogview.d.ts +255 -251
  33. package/dist/dropdown/button/dropdownbutton.d.ts +17 -17
  34. package/dist/dropdown/button/dropdownbuttonview.d.ts +41 -41
  35. package/dist/dropdown/button/splitbuttonview.d.ts +155 -155
  36. package/dist/dropdown/dropdownpanelfocusable.d.ts +16 -16
  37. package/dist/dropdown/dropdownpanelview.d.ts +56 -56
  38. package/dist/dropdown/dropdownview.d.ts +326 -326
  39. package/dist/dropdown/menu/dropdownmenubehaviors.d.ts +43 -43
  40. package/dist/dropdown/menu/dropdownmenubuttonview.d.ts +29 -29
  41. package/dist/dropdown/menu/dropdownmenulistitembuttonview.d.ts +12 -12
  42. package/dist/dropdown/menu/dropdownmenulistitemview.d.ts +17 -17
  43. package/dist/dropdown/menu/dropdownmenulistview.d.ts +19 -19
  44. package/dist/dropdown/menu/dropdownmenunestedmenupanelview.d.ts +28 -28
  45. package/dist/dropdown/menu/dropdownmenunestedmenuview.d.ts +126 -126
  46. package/dist/dropdown/menu/dropdownmenurootlistview.d.ts +132 -132
  47. package/dist/dropdown/menu/utils.d.ts +112 -112
  48. package/dist/dropdown/utils.d.ts +272 -272
  49. package/dist/editableui/editableuiview.d.ts +78 -78
  50. package/dist/editableui/inline/inlineeditableuiview.d.ts +38 -38
  51. package/dist/editorui/accessibilityhelp/accessibilityhelp.d.ts +50 -50
  52. package/dist/editorui/accessibilityhelp/accessibilityhelpcontentview.d.ts +30 -30
  53. package/dist/editorui/bodycollection.d.ts +86 -86
  54. package/dist/editorui/boxed/boxededitoruiview.d.ts +35 -35
  55. package/dist/editorui/editorui.d.ts +348 -351
  56. package/dist/editorui/editoruiview.d.ts +53 -53
  57. package/dist/editorui/evaluationbadge.d.ts +28 -28
  58. package/dist/editorui/poweredby.d.ts +25 -25
  59. package/dist/focuscycler.d.ts +265 -270
  60. package/dist/formheader/formheaderview.d.ts +53 -53
  61. package/dist/formrow/formrowview.d.ts +52 -52
  62. package/dist/highlightedtext/buttonlabelwithhighlightview.d.ts +25 -25
  63. package/dist/highlightedtext/highlightedtextview.d.ts +33 -33
  64. package/dist/highlightedtext/labelwithhighlightview.d.ts +21 -21
  65. package/dist/icon/iconview.d.ts +83 -83
  66. package/dist/iframe/iframeview.d.ts +42 -42
  67. package/dist/index.css.map +1 -1
  68. package/dist/index.d.ts +136 -136
  69. package/dist/index.js +16467 -17751
  70. package/dist/index.js.map +1 -1
  71. package/dist/input/inputbase.d.ts +114 -114
  72. package/dist/input/inputview.d.ts +28 -28
  73. package/dist/inputnumber/inputnumberview.d.ts +44 -44
  74. package/dist/inputtext/inputtextview.d.ts +13 -13
  75. package/dist/label/labelview.d.ts +31 -31
  76. package/dist/labeledfield/labeledfieldview.d.ts +180 -180
  77. package/dist/labeledfield/utils.d.ts +112 -112
  78. package/dist/labeledinput/labeledinputview.d.ts +120 -120
  79. package/dist/legacyerrors.d.ts +0 -4
  80. package/dist/list/listitemgroupview.d.ts +54 -54
  81. package/dist/list/listitemview.d.ts +31 -31
  82. package/dist/list/listseparatorview.d.ts +13 -13
  83. package/dist/list/listview.d.ts +119 -119
  84. package/dist/menubar/menubarmenubuttonview.d.ts +28 -28
  85. package/dist/menubar/menubarmenulistitembuttonview.d.ts +16 -16
  86. package/dist/menubar/menubarmenulistitemfiledialogbuttonview.d.ts +18 -18
  87. package/dist/menubar/menubarmenulistitemview.d.ts +20 -20
  88. package/dist/menubar/menubarmenulistview.d.ts +24 -24
  89. package/dist/menubar/menubarmenupanelview.d.ts +47 -47
  90. package/dist/menubar/menubarmenuview.d.ts +113 -113
  91. package/dist/menubar/menubarview.d.ts +145 -145
  92. package/dist/menubar/utils.d.ts +455 -455
  93. package/dist/model.d.ts +19 -18
  94. package/dist/notification/notification.d.ts +200 -200
  95. package/dist/panel/balloon/balloonpanelview.d.ts +692 -692
  96. package/dist/panel/balloon/contextualballoon.d.ts +298 -298
  97. package/dist/panel/sticky/stickypanelview.d.ts +151 -151
  98. package/dist/search/filteredview.d.ts +23 -23
  99. package/dist/search/filtergroupanditemnames.d.ts +11 -11
  100. package/dist/search/searchinfoview.d.ts +39 -39
  101. package/dist/search/searchresultsview.d.ts +49 -49
  102. package/dist/search/text/searchtextqueryview.d.ts +63 -63
  103. package/dist/search/text/searchtextview.d.ts +203 -203
  104. package/dist/spinner/spinnerview.d.ts +20 -20
  105. package/dist/template.d.ts +897 -902
  106. package/dist/textarea/textareaview.d.ts +96 -96
  107. package/dist/toolbar/balloon/balloontoolbar.d.ts +122 -122
  108. package/dist/toolbar/block/blockbuttonview.d.ts +30 -30
  109. package/dist/toolbar/block/blocktoolbar.d.ts +166 -166
  110. package/dist/toolbar/normalizetoolbarconfig.d.ts +35 -35
  111. package/dist/toolbar/toolbarlinebreakview.d.ts +13 -13
  112. package/dist/toolbar/toolbarseparatorview.d.ts +13 -13
  113. package/dist/toolbar/toolbarview.d.ts +271 -271
  114. package/dist/tooltipmanager.d.ts +190 -193
  115. package/dist/view.d.ts +385 -388
  116. package/dist/viewcollection.d.ts +134 -134
  117. package/package.json +6 -6
@@ -1,946 +1,941 @@
1
1
  /**
2
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
3
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
- */
2
+ * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
3
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
+ */
5
5
  /**
6
- * @module ui/template
7
- */
8
- import { View } from './view.js';
9
- import { ViewCollection } from './viewcollection.js';
10
- import { type ArrayOrItem, type Emitter, type Observable } from '@ckeditor/ckeditor5-utils';
11
- declare const Template_base: {
12
- new (): Emitter;
13
- prototype: Emitter;
14
- };
6
+ * @module ui/template
7
+ */
8
+ import { View } from "./view.js";
9
+ import { ViewCollection } from "./viewcollection.js";
10
+ import { type ArrayOrItem, type Emitter, type Observable, type EmitterMixinConstructor } from "@ckeditor/ckeditor5-utils";
11
+ declare const TemplateBase: EmitterMixinConstructor;
15
12
  /**
16
- * A basic Template class. It renders a DOM HTML element or text from a
17
- * {@link module:ui/template~TemplateDefinition definition} and supports element attributes, children,
18
- * bindings to {@link module:utils/observablemixin~Observable observables} and DOM event propagation.
19
- *
20
- * A simple template can look like this:
21
- *
22
- * ```ts
23
- * const bind = Template.bind( observable, emitter );
24
- *
25
- * new Template( {
26
- * tag: 'p',
27
- * attributes: {
28
- * class: 'foo',
29
- * style: {
30
- * backgroundColor: 'yellow'
31
- * }
32
- * },
33
- * on: {
34
- * click: bind.to( 'clicked' )
35
- * },
36
- * children: [
37
- * 'A paragraph.'
38
- * ]
39
- * } ).render();
40
- * ```
41
- *
42
- * and it will render the following HTML element:
43
- *
44
- * ```html
45
- * <p class="foo" style="background-color: yellow;">A paragraph.</p>
46
- * ```
47
- *
48
- * Additionally, the `observable` will always fire `clicked` upon clicking `<p>` in the DOM.
49
- *
50
- * See {@link module:ui/template~TemplateDefinition} to know more about templates and complex
51
- * template definitions.
52
- */
53
- export declare class Template extends /* #__PURE__ */ Template_base {
54
- ns?: string;
55
- /**
56
- * The tag (`tagName`) of this template, e.g. `div`. It also indicates that the template
57
- * renders to an HTML element.
58
- */
59
- tag?: string;
60
- /**
61
- * The text of the template. It also indicates that the template renders to a DOM text node.
62
- */
63
- text?: Array<TemplateSimpleValue | TemplateBinding>;
64
- /**
65
- * The attributes of the template, e.g. `{ id: [ 'ck-id' ] }`, corresponding with
66
- * the attributes of an HTML element.
67
- *
68
- * **Note**: This property only makes sense when {@link #tag} is defined.
69
- */
70
- attributes?: Record<string, AttributeValues>;
71
- /**
72
- * The children of the template. They can be either:
73
- * * independent instances of {@link ~Template} (sub–templates),
74
- * * native DOM Nodes.
75
- *
76
- * **Note**: This property only makes sense when {@link #tag} is defined.
77
- */
78
- children?: Array<ViewCollection | View | Node | Template>;
79
- /**
80
- * The DOM event listeners of the template.
81
- */
82
- eventListeners?: Record<string, Array<TemplateToBinding>>;
83
- /**
84
- * Indicates whether this particular Template instance has been
85
- * {@link #render rendered}.
86
- */
87
- private _isRendered;
88
- /**
89
- * The data used by the {@link #revert} method to restore a node to its original state.
90
- *
91
- * See: {@link #apply}.
92
- */
93
- private _revertData;
94
- /**
95
- * Creates an instance of the {@link ~Template} class.
96
- *
97
- * @param def The definition of the template.
98
- */
99
- constructor(def: TemplateDefinition);
100
- /**
101
- * Renders a DOM Node (an HTML element or text) out of the template.
102
- *
103
- * ```ts
104
- * const domNode = new Template( { ... } ).render();
105
- * ```
106
- *
107
- * See: {@link #apply}.
108
- */
109
- render(): HTMLElement | Text;
110
- /**
111
- * Applies the template to an existing DOM Node, either HTML element or text.
112
- *
113
- * **Note:** No new DOM nodes will be created. Applying extends:
114
- *
115
- * {@link module:ui/template~TemplateDefinition attributes},
116
- * {@link module:ui/template~TemplateDefinition event listeners}, and
117
- * `textContent` of {@link module:ui/template~TemplateDefinition children} only.
118
- *
119
- * **Note:** Existing `class` and `style` attributes are extended when a template
120
- * is applied to an HTML element, while other attributes and `textContent` are overridden.
121
- *
122
- * **Note:** The process of applying a template can be easily reverted using the
123
- * {@link module:ui/template~Template#revert} method.
124
- *
125
- * ```ts
126
- * const element = document.createElement( 'div' );
127
- * const observable = new Model( { divClass: 'my-div' } );
128
- * const emitter = Object.create( EmitterMixin );
129
- * const bind = Template.bind( observable, emitter );
130
- *
131
- * new Template( {
132
- * attributes: {
133
- * id: 'first-div',
134
- * class: bind.to( 'divClass' )
135
- * },
136
- * on: {
137
- * click: bind( 'elementClicked' ) // Will be fired by the observable.
138
- * },
139
- * children: [
140
- * 'Div text.'
141
- * ]
142
- * } ).apply( element );
143
- *
144
- * console.log( element.outerHTML ); // -> '<div id="first-div" class="my-div"></div>'
145
- * ```
146
- *
147
- * @see module:ui/template~Template#render
148
- * @see module:ui/template~Template#revert
149
- * @param node Root node for the template to apply.
150
- */
151
- apply(node: HTMLElement | Text): HTMLElement | Text;
152
- /**
153
- * Reverts a template {@link module:ui/template~Template#apply applied} to a DOM node.
154
- *
155
- * @param node The root node for the template to revert. In most of the cases, it is the
156
- * same node used by {@link module:ui/template~Template#apply}.
157
- */
158
- revert(node: HTMLElement | Text): void;
159
- /**
160
- * Returns an iterator which traverses the template in search of {@link module:ui/view~View}
161
- * instances and returns them one by one.
162
- *
163
- * ```ts
164
- * const viewFoo = new View();
165
- * const viewBar = new View();
166
- * const viewBaz = new View();
167
- * const template = new Template( {
168
- * tag: 'div',
169
- * children: [
170
- * viewFoo,
171
- * {
172
- * tag: 'div',
173
- * children: [
174
- * viewBar
175
- * ]
176
- * },
177
- * viewBaz
178
- * ]
179
- * } );
180
- *
181
- * // Logs: viewFoo, viewBar, viewBaz
182
- * for ( const view of template.getViews() ) {
183
- * console.log( view );
184
- * }
185
- * ```
186
- */
187
- getViews(): IterableIterator<View>;
188
- /**
189
- * An entry point to the interface which binds DOM nodes to
190
- * {@link module:utils/observablemixin~Observable observables}.
191
- * There are two types of bindings:
192
- *
193
- * * HTML element attributes or text `textContent` synchronized with attributes of an
194
- * {@link module:utils/observablemixin~Observable}. Learn more about {@link module:ui/template~BindChain#to}
195
- * and {@link module:ui/template~BindChain#if}.
196
- *
197
- * ```ts
198
- * const bind = Template.bind( observable, emitter );
199
- *
200
- * new Template( {
201
- * attributes: {
202
- * // Binds the element "class" attribute to observable#classAttribute.
203
- * class: bind.to( 'classAttribute' )
204
- * }
205
- * } ).render();
206
- * ```
207
- *
208
- * * DOM events fired on HTML element propagated through
209
- * {@link module:utils/observablemixin~Observable}. Learn more about {@link module:ui/template~BindChain#to}.
210
- *
211
- * ```ts
212
- * const bind = Template.bind( observable, emitter );
213
- *
214
- * new Template( {
215
- * on: {
216
- * // Will be fired by the observable.
217
- * click: bind( 'elementClicked' )
218
- * }
219
- * } ).render();
220
- * ```
221
- *
222
- * Also see {@link module:ui/view~View#bindTemplate}.
223
- *
224
- * @param observable An observable which provides boundable attributes.
225
- * @param emitter An emitter that listens to observable attribute
226
- * changes or DOM Events (depending on the kind of the binding). Usually, a {@link module:ui/view~View} instance.
227
- */
228
- static bind<TObservable extends Observable>(observable: TObservable, emitter: Emitter): BindChain<TObservable>;
229
- /**
230
- * Extends an existing {@link module:ui/template~Template} instance with some additional content
231
- * from another {@link module:ui/template~TemplateDefinition}.
232
- *
233
- * ```ts
234
- * const bind = Template.bind( observable, emitter );
235
- *
236
- * const template = new Template( {
237
- * tag: 'p',
238
- * attributes: {
239
- * class: 'a',
240
- * data-x: bind.to( 'foo' )
241
- * },
242
- * children: [
243
- * {
244
- * tag: 'span',
245
- * attributes: {
246
- * class: 'b'
247
- * },
248
- * children: [
249
- * 'Span'
250
- * ]
251
- * }
252
- * ]
253
- * } );
254
- *
255
- * // Instance-level extension.
256
- * Template.extend( template, {
257
- * attributes: {
258
- * class: 'b',
259
- * data-x: bind.to( 'bar' )
260
- * },
261
- * children: [
262
- * {
263
- * attributes: {
264
- * class: 'c'
265
- * }
266
- * }
267
- * ]
268
- * } );
269
- *
270
- * // Child extension.
271
- * Template.extend( template.children[ 0 ], {
272
- * attributes: {
273
- * class: 'd'
274
- * }
275
- * } );
276
- * ```
277
- *
278
- * the `outerHTML` of `template.render()` is:
279
- *
280
- * ```html
281
- * <p class="a b" data-x="{ observable.foo } { observable.bar }">
282
- * <span class="b c d">Span</span>
283
- * </p>
284
- * ```
285
- *
286
- * @param template An existing template instance to be extended.
287
- * @param def Additional definition to be applied to a template.
288
- */
289
- static extend(template: Template, def: Partial<TemplateDefinition>): void;
290
- /**
291
- * Renders a DOM Node (either an HTML element or text) out of the template.
292
- *
293
- * @param data Rendering data.
294
- */
295
- private _renderNode;
296
- /**
297
- * Renders an HTML element out of the template.
298
- *
299
- * @param data Rendering data.
300
- */
301
- private _renderElement;
302
- /**
303
- * Renders a text node out of {@link module:ui/template~Template#text}.
304
- *
305
- * @param data Rendering data.
306
- */
307
- private _renderText;
308
- /**
309
- * Renders HTML element attributes out of {@link module:ui/template~Template#attributes}.
310
- *
311
- * @param data Rendering data.
312
- */
313
- private _renderAttributes;
314
- /**
315
- * Renders the `style` attribute of an HTML element based on
316
- * {@link module:ui/template~Template#attributes}.
317
- *
318
- * A style attribute is an object with static values:
319
- *
320
- * ```ts
321
- * attributes: {
322
- * style: {
323
- * color: 'red',
324
- * '--color': 'red'
325
- * }
326
- * }
327
- * ```
328
- *
329
- * or values bound to {@link module:ui/model~UIModel} properties:
330
- *
331
- * ```ts
332
- * attributes: {
333
- * style: {
334
- * color: bind.to( ... ),
335
- * '--color': bind.to( ... )
336
- * }
337
- * }
338
- * ```
339
- *
340
- * Note: The `style` attribute is rendered without setting the namespace. It does not seem to be
341
- * needed.
342
- *
343
- * @param styles Styles located in `attributes.style` of {@link module:ui/template~TemplateDefinition}.
344
- * @param data Rendering data.
345
- */
346
- private _renderStyleAttribute;
347
- /**
348
- * Recursively renders HTML element's children from {@link module:ui/template~Template#children}.
349
- *
350
- * @param data Rendering data.
351
- */
352
- private _renderElementChildren;
353
- /**
354
- * Activates `on` event listeners from the {@link module:ui/template~TemplateDefinition}
355
- * on an HTML element.
356
- *
357
- * @param data Rendering data.
358
- */
359
- private _setUpListeners;
360
- /**
361
- * For a given {@link module:ui/template~TemplateValueSchema} containing {@link module:ui/template~TemplateBinding}
362
- * activates the binding and sets its initial value.
363
- *
364
- * Note: {@link module:ui/template~TemplateValueSchema} can be for HTML element attributes or
365
- * text node `textContent`.
366
- *
367
- * @param options Binding options.
368
- * @param options.updater A function which updates the DOM (like attribute or text).
369
- * @param options.data Rendering data.
370
- */
371
- private _bindToObservable;
372
- /**
373
- * Reverts {@link module:ui/template~RenderData#revertData template data} from a node to
374
- * return it to the original state.
375
- *
376
- * @param node A node to be reverted.
377
- * @param revertData An object that stores information about what changes have been made by
378
- * {@link #apply} to the node. See {@link module:ui/template~RenderData#revertData} for more information.
379
- */
380
- private _revertTemplateFromNode;
13
+ * A basic Template class. It renders a DOM HTML element or text from a
14
+ * {@link module:ui/template~TemplateDefinition definition} and supports element attributes, children,
15
+ * bindings to {@link module:utils/observablemixin~Observable observables} and DOM event propagation.
16
+ *
17
+ * A simple template can look like this:
18
+ *
19
+ * ```ts
20
+ * const bind = Template.bind( observable, emitter );
21
+ *
22
+ * new Template( {
23
+ * tag: 'p',
24
+ * attributes: {
25
+ * class: 'foo',
26
+ * style: {
27
+ * backgroundColor: 'yellow'
28
+ * }
29
+ * },
30
+ * on: {
31
+ * click: bind.to( 'clicked' )
32
+ * },
33
+ * children: [
34
+ * 'A paragraph.'
35
+ * ]
36
+ * } ).render();
37
+ * ```
38
+ *
39
+ * and it will render the following HTML element:
40
+ *
41
+ * ```html
42
+ * <p class="foo" style="background-color: yellow;">A paragraph.</p>
43
+ * ```
44
+ *
45
+ * Additionally, the `observable` will always fire `clicked` upon clicking `<p>` in the DOM.
46
+ *
47
+ * See {@link module:ui/template~TemplateDefinition} to know more about templates and complex
48
+ * template definitions.
49
+ */
50
+ export declare class Template extends TemplateBase {
51
+ ns?: string;
52
+ /**
53
+ * The tag (`tagName`) of this template, e.g. `div`. It also indicates that the template
54
+ * renders to an HTML element.
55
+ */
56
+ tag?: string;
57
+ /**
58
+ * The text of the template. It also indicates that the template renders to a DOM text node.
59
+ */
60
+ text?: Array<TemplateSimpleValue | TemplateBinding>;
61
+ /**
62
+ * The attributes of the template, e.g. `{ id: [ 'ck-id' ] }`, corresponding with
63
+ * the attributes of an HTML element.
64
+ *
65
+ * **Note**: This property only makes sense when {@link #tag} is defined.
66
+ */
67
+ attributes?: Record<string, AttributeValues>;
68
+ /**
69
+ * The children of the template. They can be either:
70
+ * * independent instances of {@link ~Template} (sub–templates),
71
+ * * native DOM Nodes.
72
+ *
73
+ * **Note**: This property only makes sense when {@link #tag} is defined.
74
+ */
75
+ children?: Array<ViewCollection | View | Node | Template>;
76
+ /**
77
+ * The DOM event listeners of the template.
78
+ */
79
+ eventListeners?: Record<string, Array<TemplateToBinding>>;
80
+ /**
81
+ * Indicates whether this particular Template instance has been
82
+ * {@link #render rendered}.
83
+ */
84
+ private _isRendered;
85
+ /**
86
+ * The data used by the {@link #revert} method to restore a node to its original state.
87
+ *
88
+ * See: {@link #apply}.
89
+ */
90
+ private _revertData;
91
+ /**
92
+ * Creates an instance of the {@link ~Template} class.
93
+ *
94
+ * @param def The definition of the template.
95
+ */
96
+ constructor(def: TemplateDefinition);
97
+ /**
98
+ * Renders a DOM Node (an HTML element or text) out of the template.
99
+ *
100
+ * ```ts
101
+ * const domNode = new Template( { ... } ).render();
102
+ * ```
103
+ *
104
+ * See: {@link #apply}.
105
+ */
106
+ render(): HTMLElement | Text;
107
+ /**
108
+ * Applies the template to an existing DOM Node, either HTML element or text.
109
+ *
110
+ * **Note:** No new DOM nodes will be created. Applying extends:
111
+ *
112
+ * {@link module:ui/template~TemplateDefinition attributes},
113
+ * {@link module:ui/template~TemplateDefinition event listeners}, and
114
+ * `textContent` of {@link module:ui/template~TemplateDefinition children} only.
115
+ *
116
+ * **Note:** Existing `class` and `style` attributes are extended when a template
117
+ * is applied to an HTML element, while other attributes and `textContent` are overridden.
118
+ *
119
+ * **Note:** The process of applying a template can be easily reverted using the
120
+ * {@link module:ui/template~Template#revert} method.
121
+ *
122
+ * ```ts
123
+ * const element = document.createElement( 'div' );
124
+ * const observable = new Model( { divClass: 'my-div' } );
125
+ * const emitter = Object.create( EmitterMixin );
126
+ * const bind = Template.bind( observable, emitter );
127
+ *
128
+ * new Template( {
129
+ * attributes: {
130
+ * id: 'first-div',
131
+ * class: bind.to( 'divClass' )
132
+ * },
133
+ * on: {
134
+ * click: bind( 'elementClicked' ) // Will be fired by the observable.
135
+ * },
136
+ * children: [
137
+ * 'Div text.'
138
+ * ]
139
+ * } ).apply( element );
140
+ *
141
+ * console.log( element.outerHTML ); // -> '<div id="first-div" class="my-div"></div>'
142
+ * ```
143
+ *
144
+ * @see module:ui/template~Template#render
145
+ * @see module:ui/template~Template#revert
146
+ * @param node Root node for the template to apply.
147
+ */
148
+ apply(node: HTMLElement | Text): HTMLElement | Text;
149
+ /**
150
+ * Reverts a template {@link module:ui/template~Template#apply applied} to a DOM node.
151
+ *
152
+ * @param node The root node for the template to revert. In most of the cases, it is the
153
+ * same node used by {@link module:ui/template~Template#apply}.
154
+ */
155
+ revert(node: HTMLElement | Text): void;
156
+ /**
157
+ * Returns an iterator which traverses the template in search of {@link module:ui/view~View}
158
+ * instances and returns them one by one.
159
+ *
160
+ * ```ts
161
+ * const viewFoo = new View();
162
+ * const viewBar = new View();
163
+ * const viewBaz = new View();
164
+ * const template = new Template( {
165
+ * tag: 'div',
166
+ * children: [
167
+ * viewFoo,
168
+ * {
169
+ * tag: 'div',
170
+ * children: [
171
+ * viewBar
172
+ * ]
173
+ * },
174
+ * viewBaz
175
+ * ]
176
+ * } );
177
+ *
178
+ * // Logs: viewFoo, viewBar, viewBaz
179
+ * for ( const view of template.getViews() ) {
180
+ * console.log( view );
181
+ * }
182
+ * ```
183
+ */
184
+ getViews(): IterableIterator<View>;
185
+ /**
186
+ * An entry point to the interface which binds DOM nodes to
187
+ * {@link module:utils/observablemixin~Observable observables}.
188
+ * There are two types of bindings:
189
+ *
190
+ * * HTML element attributes or text `textContent` synchronized with attributes of an
191
+ * {@link module:utils/observablemixin~Observable}. Learn more about {@link module:ui/template~BindChain#to}
192
+ * and {@link module:ui/template~BindChain#if}.
193
+ *
194
+ * ```ts
195
+ * const bind = Template.bind( observable, emitter );
196
+ *
197
+ * new Template( {
198
+ * attributes: {
199
+ * // Binds the element "class" attribute to observable#classAttribute.
200
+ * class: bind.to( 'classAttribute' )
201
+ * }
202
+ * } ).render();
203
+ * ```
204
+ *
205
+ * * DOM events fired on HTML element propagated through
206
+ * {@link module:utils/observablemixin~Observable}. Learn more about {@link module:ui/template~BindChain#to}.
207
+ *
208
+ * ```ts
209
+ * const bind = Template.bind( observable, emitter );
210
+ *
211
+ * new Template( {
212
+ * on: {
213
+ * // Will be fired by the observable.
214
+ * click: bind( 'elementClicked' )
215
+ * }
216
+ * } ).render();
217
+ * ```
218
+ *
219
+ * Also see {@link module:ui/view~View#bindTemplate}.
220
+ *
221
+ * @param observable An observable which provides boundable attributes.
222
+ * @param emitter An emitter that listens to observable attribute
223
+ * changes or DOM Events (depending on the kind of the binding). Usually, a {@link module:ui/view~View} instance.
224
+ */
225
+ static override bind<TObservable extends Observable>(observable: TObservable, emitter: Emitter): BindChain<TObservable>;
226
+ /**
227
+ * Extends an existing {@link module:ui/template~Template} instance with some additional content
228
+ * from another {@link module:ui/template~TemplateDefinition}.
229
+ *
230
+ * ```ts
231
+ * const bind = Template.bind( observable, emitter );
232
+ *
233
+ * const template = new Template( {
234
+ * tag: 'p',
235
+ * attributes: {
236
+ * class: 'a',
237
+ * data-x: bind.to( 'foo' )
238
+ * },
239
+ * children: [
240
+ * {
241
+ * tag: 'span',
242
+ * attributes: {
243
+ * class: 'b'
244
+ * },
245
+ * children: [
246
+ * 'Span'
247
+ * ]
248
+ * }
249
+ * ]
250
+ * } );
251
+ *
252
+ * // Instance-level extension.
253
+ * Template.extend( template, {
254
+ * attributes: {
255
+ * class: 'b',
256
+ * data-x: bind.to( 'bar' )
257
+ * },
258
+ * children: [
259
+ * {
260
+ * attributes: {
261
+ * class: 'c'
262
+ * }
263
+ * }
264
+ * ]
265
+ * } );
266
+ *
267
+ * // Child extension.
268
+ * Template.extend( template.children[ 0 ], {
269
+ * attributes: {
270
+ * class: 'd'
271
+ * }
272
+ * } );
273
+ * ```
274
+ *
275
+ * the `outerHTML` of `template.render()` is:
276
+ *
277
+ * ```html
278
+ * <p class="a b" data-x="{ observable.foo } { observable.bar }">
279
+ * <span class="b c d">Span</span>
280
+ * </p>
281
+ * ```
282
+ *
283
+ * @param template An existing template instance to be extended.
284
+ * @param def Additional definition to be applied to a template.
285
+ */
286
+ static extend(template: Template, def: Partial<TemplateDefinition>): void;
287
+ /**
288
+ * Renders a DOM Node (either an HTML element or text) out of the template.
289
+ *
290
+ * @param data Rendering data.
291
+ */
292
+ private _renderNode;
293
+ /**
294
+ * Renders an HTML element out of the template.
295
+ *
296
+ * @param data Rendering data.
297
+ */
298
+ private _renderElement;
299
+ /**
300
+ * Renders a text node out of {@link module:ui/template~Template#text}.
301
+ *
302
+ * @param data Rendering data.
303
+ */
304
+ private _renderText;
305
+ /**
306
+ * Renders HTML element attributes out of {@link module:ui/template~Template#attributes}.
307
+ *
308
+ * @param data Rendering data.
309
+ */
310
+ private _renderAttributes;
311
+ /**
312
+ * Renders the `style` attribute of an HTML element based on
313
+ * {@link module:ui/template~Template#attributes}.
314
+ *
315
+ * A style attribute is an object with static values:
316
+ *
317
+ * ```ts
318
+ * attributes: {
319
+ * style: {
320
+ * color: 'red',
321
+ * '--color': 'red'
322
+ * }
323
+ * }
324
+ * ```
325
+ *
326
+ * or values bound to {@link module:ui/model~UIModel} properties:
327
+ *
328
+ * ```ts
329
+ * attributes: {
330
+ * style: {
331
+ * color: bind.to( ... ),
332
+ * '--color': bind.to( ... )
333
+ * }
334
+ * }
335
+ * ```
336
+ *
337
+ * Note: The `style` attribute is rendered without setting the namespace. It does not seem to be
338
+ * needed.
339
+ *
340
+ * @param styles Styles located in `attributes.style` of {@link module:ui/template~TemplateDefinition}.
341
+ * @param data Rendering data.
342
+ */
343
+ private _renderStyleAttribute;
344
+ /**
345
+ * Recursively renders HTML element's children from {@link module:ui/template~Template#children}.
346
+ *
347
+ * @param data Rendering data.
348
+ */
349
+ private _renderElementChildren;
350
+ /**
351
+ * Activates `on` event listeners from the {@link module:ui/template~TemplateDefinition}
352
+ * on an HTML element.
353
+ *
354
+ * @param data Rendering data.
355
+ */
356
+ private _setUpListeners;
357
+ /**
358
+ * For a given {@link module:ui/template~TemplateValueSchema} containing {@link module:ui/template~TemplateBinding}
359
+ * activates the binding and sets its initial value.
360
+ *
361
+ * Note: {@link module:ui/template~TemplateValueSchema} can be for HTML element attributes or
362
+ * text node `textContent`.
363
+ *
364
+ * @param options Binding options.
365
+ * @param options.updater A function which updates the DOM (like attribute or text).
366
+ * @param options.data Rendering data.
367
+ */
368
+ private _bindToObservable;
369
+ /**
370
+ * Reverts {@link module:ui/template~RenderData#revertData template data} from a node to
371
+ * return it to the original state.
372
+ *
373
+ * @param node A node to be reverted.
374
+ * @param revertData An object that stores information about what changes have been made by
375
+ * {@link #apply} to the node. See {@link module:ui/template~RenderData#revertData} for more information.
376
+ */
377
+ private _revertTemplateFromNode;
381
378
  }
382
- export type AttributeValues = Array<TemplateSimpleValue | TemplateBinding> | [
383
- NamespacedValue<Array<TemplateSimpleValue | TemplateBinding>>
384
- ];
379
+ export type AttributeValues = Array<TemplateSimpleValue | TemplateBinding> | [NamespacedValue<Array<TemplateSimpleValue | TemplateBinding>>];
385
380
  /**
386
- * Describes a binding created by the {@link module:ui/template~Template.bind} interface.
387
- *
388
- * @internal
389
- */
381
+ * Describes a binding created by the {@link module:ui/template~Template.bind} interface.
382
+ *
383
+ * @internal
384
+ */
390
385
  export declare abstract class TemplateBinding {
391
- /**
392
- * The name of the {@link module:ui/template~TemplateBinding#observable observed attribute}.
393
- */
394
- readonly attribute: string;
395
- /**
396
- * An observable instance of the binding. It either:
397
- *
398
- * * provides the attribute with the value,
399
- * * or passes the event when a corresponding DOM event is fired.
400
- */
401
- readonly observable: Observable;
402
- /**
403
- * An {@link module:utils/emittermixin~Emitter} used by the binding to:
404
- *
405
- * * listen to the attribute change in the {@link module:ui/template~TemplateBinding#observable},
406
- * * or listen to the event in the DOM.
407
- */
408
- readonly emitter: Emitter;
409
- /**
410
- * A custom function to process the value of the {@link module:ui/template~TemplateBinding#attribute}.
411
- */
412
- readonly callback?: (value: any, node: Node) => TemplateSimpleValue;
413
- /**
414
- * Creates an instance of the {@link module:ui/template~TemplateBinding} class.
415
- *
416
- * @param def The definition of the binding.
417
- */
418
- constructor(def: {
419
- attribute: string;
420
- observable: Observable;
421
- emitter: Emitter;
422
- callback?: (value: any, node: Node) => TemplateSimpleValue;
423
- });
424
- /**
425
- * Returns the value of the binding. It is the value of the {@link module:ui/template~TemplateBinding#attribute} in
426
- * {@link module:ui/template~TemplateBinding#observable}. The value may be processed by the
427
- * {@link module:ui/template~TemplateBinding#callback}, if such has been passed to the binding.
428
- *
429
- * @param node A native DOM node, passed to the custom {@link module:ui/template~TemplateBinding#callback}.
430
- * @returns The value of {@link module:ui/template~TemplateBinding#attribute} in
431
- * {@link module:ui/template~TemplateBinding#observable}.
432
- */
433
- getValue(node: Node): TemplateSimpleValue;
434
- /**
435
- * Activates the listener which waits for changes of the {@link module:ui/template~TemplateBinding#attribute} in
436
- * {@link module:ui/template~TemplateBinding#observable}, then updates the DOM with the aggregated
437
- * value of {@link module:ui/template~TemplateValueSchema}.
438
- *
439
- * @param schema A full schema to generate an attribute or text in the DOM.
440
- * @param updater A DOM updater function used to update the native DOM attribute or text.
441
- * @param data Rendering data.
442
- * @returns A function to sever the listener binding.
443
- */
444
- activateAttributeListener(schema: Array<TemplateSimpleValue | TemplateBinding>, updater: Updater, data: RenderData): () => void;
386
+ /**
387
+ * The name of the {@link module:ui/template~TemplateBinding#observable observed attribute}.
388
+ */
389
+ readonly attribute: string;
390
+ /**
391
+ * An observable instance of the binding. It either:
392
+ *
393
+ * * provides the attribute with the value,
394
+ * * or passes the event when a corresponding DOM event is fired.
395
+ */
396
+ readonly observable: Observable;
397
+ /**
398
+ * An {@link module:utils/emittermixin~Emitter} used by the binding to:
399
+ *
400
+ * * listen to the attribute change in the {@link module:ui/template~TemplateBinding#observable},
401
+ * * or listen to the event in the DOM.
402
+ */
403
+ readonly emitter: Emitter;
404
+ /**
405
+ * A custom function to process the value of the {@link module:ui/template~TemplateBinding#attribute}.
406
+ */
407
+ readonly callback?: (value: any, node: Node) => TemplateSimpleValue;
408
+ /**
409
+ * Creates an instance of the {@link module:ui/template~TemplateBinding} class.
410
+ *
411
+ * @param def The definition of the binding.
412
+ */
413
+ constructor(def: {
414
+ attribute: string;
415
+ observable: Observable;
416
+ emitter: Emitter;
417
+ callback?: (value: any, node: Node) => TemplateSimpleValue;
418
+ });
419
+ /**
420
+ * Returns the value of the binding. It is the value of the {@link module:ui/template~TemplateBinding#attribute} in
421
+ * {@link module:ui/template~TemplateBinding#observable}. The value may be processed by the
422
+ * {@link module:ui/template~TemplateBinding#callback}, if such has been passed to the binding.
423
+ *
424
+ * @param node A native DOM node, passed to the custom {@link module:ui/template~TemplateBinding#callback}.
425
+ * @returns The value of {@link module:ui/template~TemplateBinding#attribute} in
426
+ * {@link module:ui/template~TemplateBinding#observable}.
427
+ */
428
+ getValue(node: Node): TemplateSimpleValue;
429
+ /**
430
+ * Activates the listener which waits for changes of the {@link module:ui/template~TemplateBinding#attribute} in
431
+ * {@link module:ui/template~TemplateBinding#observable}, then updates the DOM with the aggregated
432
+ * value of {@link module:ui/template~TemplateValueSchema}.
433
+ *
434
+ * @param schema A full schema to generate an attribute or text in the DOM.
435
+ * @param updater A DOM updater function used to update the native DOM attribute or text.
436
+ * @param data Rendering data.
437
+ * @returns A function to sever the listener binding.
438
+ */
439
+ activateAttributeListener(schema: Array<TemplateSimpleValue | TemplateBinding>, updater: Updater, data: RenderData): () => void;
445
440
  }
446
441
  /**
447
- * Describes either:
448
- *
449
- * * a binding to an {@link module:utils/observablemixin~Observable},
450
- * * or a native DOM event binding.
451
- *
452
- * It is created by the {@link module:ui/template~BindChain#to} method.
453
- *
454
- * @internal
455
- */
442
+ * Describes either:
443
+ *
444
+ * * a binding to an {@link module:utils/observablemixin~Observable},
445
+ * * or a native DOM event binding.
446
+ *
447
+ * It is created by the {@link module:ui/template~BindChain#to} method.
448
+ *
449
+ * @internal
450
+ */
456
451
  export declare class TemplateToBinding extends TemplateBinding {
457
- readonly eventNameOrFunction: string | ((domEvent: Event) => void);
458
- constructor(def: ConstructorParameters<typeof TemplateBinding>[0] & {
459
- eventNameOrFunction: string | ((domEvent: Event) => void);
460
- });
461
- /**
462
- * Activates the listener for the native DOM event, which when fired, is propagated by
463
- * the {@link module:ui/template~TemplateBinding#emitter}.
464
- *
465
- * @param domEvtName The name of the native DOM event.
466
- * @param domSelector The selector in the DOM to filter delegated events.
467
- * @param data Rendering data.
468
- * @returns A function to sever the listener binding.
469
- */
470
- activateDomEventListener(domEvtName: string, domSelector: string, data: {
471
- node: any;
472
- }): () => void;
452
+ readonly eventNameOrFunction: string | ((domEvent: Event) => void);
453
+ constructor(def: ConstructorParameters<typeof TemplateBinding>[0] & {
454
+ eventNameOrFunction: string | ((domEvent: Event) => void);
455
+ });
456
+ /**
457
+ * Activates the listener for the native DOM event, which when fired, is propagated by
458
+ * the {@link module:ui/template~TemplateBinding#emitter}.
459
+ *
460
+ * @param domEvtName The name of the native DOM event.
461
+ * @param domSelector The selector in the DOM to filter delegated events.
462
+ * @param data Rendering data.
463
+ * @returns A function to sever the listener binding.
464
+ */
465
+ activateDomEventListener(domEvtName: string, domSelector: string, data: {
466
+ node: any;
467
+ }): () => void;
473
468
  }
474
469
  /**
475
- * Describes a binding to {@link module:utils/observablemixin~Observable} created by the {@link module:ui/template~BindChain#if}
476
- * method.
477
- *
478
- * @internal
479
- */
470
+ * Describes a binding to {@link module:utils/observablemixin~Observable} created by the {@link module:ui/template~BindChain#if}
471
+ * method.
472
+ *
473
+ * @internal
474
+ */
480
475
  export declare class TemplateIfBinding extends TemplateBinding {
481
- /**
482
- * The value of the DOM attribute or text to be set if the {@link module:ui/template~TemplateBinding#attribute} in
483
- * {@link module:ui/template~TemplateBinding#observable} is `true`.
484
- */
485
- readonly valueIfTrue?: string;
486
- constructor(def: ConstructorParameters<typeof TemplateBinding>[0] & {
487
- valueIfTrue?: string;
488
- });
489
- /**
490
- * @inheritDoc
491
- */
492
- getValue(node: Node): TemplateSimpleValue;
476
+ /**
477
+ * The value of the DOM attribute or text to be set if the {@link module:ui/template~TemplateBinding#attribute} in
478
+ * {@link module:ui/template~TemplateBinding#observable} is `true`.
479
+ */
480
+ readonly valueIfTrue?: string;
481
+ constructor(def: ConstructorParameters<typeof TemplateBinding>[0] & {
482
+ valueIfTrue?: string;
483
+ });
484
+ /**
485
+ * @inheritDoc
486
+ */
487
+ override getValue(node: Node): TemplateSimpleValue;
493
488
  }
494
489
  interface Updater {
495
- set(value: any): void;
496
- remove(): void;
490
+ set(value: any): void;
491
+ remove(): void;
497
492
  }
498
493
  /**
499
- * A definition of the {@link module:ui/template~Template}. It describes what kind of
500
- * node a template will render (HTML element or text), attributes of an element, DOM event
501
- * listeners and children.
502
- *
503
- * Also see:
504
- * * {@link module:ui/template~TemplateValueSchema} to learn about HTML element attributes,
505
- * * {@link module:ui/template~TemplateListenerSchema} to learn about DOM event listeners.
506
- *
507
- * A sample definition on an HTML element can look like this:
508
- *
509
- * ```ts
510
- * new Template( {
511
- * tag: 'p',
512
- * children: [
513
- * {
514
- * tag: 'span',
515
- * attributes: { ... },
516
- * children: [ ... ],
517
- * },
518
- * {
519
- * text: 'static–text'
520
- * },
521
- * 'also-static–text',
522
- * ],
523
- * attributes: {
524
- * class: {@link module:ui/template~TemplateValueSchema},
525
- * id: {@link module:ui/template~TemplateValueSchema},
526
- * style: {@link module:ui/template~TemplateValueSchema}
527
- *
528
- * // ...
529
- * },
530
- * on: {
531
- * 'click': {@link module:ui/template~TemplateListenerSchema}
532
- *
533
- * // Document.querySelector format is also accepted.
534
- * 'keyup@a.some-class': {@link module:ui/template~TemplateListenerSchema}
535
- *
536
- * // ...
537
- * }
538
- * } );
539
- * ```
540
- *
541
- * A {@link module:ui/view~View}, another {@link module:ui/template~Template} or a native DOM node
542
- * can also become a child of a template. When a view is passed, its {@link module:ui/view~View#element} is used:
543
- *
544
- * ```ts
545
- * const view = new SomeView();
546
- * const childTemplate = new Template( { ... } );
547
- * const childNode = document.createElement( 'b' );
548
- *
549
- * new Template( {
550
- * tag: 'p',
551
- *
552
- * children: [
553
- * // view#element will be added as a child of this <p>.
554
- * view,
555
- *
556
- * // The output of childTemplate.render() will be added here.
557
- * childTemplate,
558
- *
559
- * // Native DOM nodes are included directly in the rendered output.
560
- * childNode
561
- * ]
562
- * } );
563
- * ```
564
- *
565
- * An entire {@link module:ui/viewcollection~ViewCollection} can be used as a child in the definition:
566
- *
567
- * ```ts
568
- * const collection = new ViewCollection();
569
- * collection.add( someView );
570
- *
571
- * new Template( {
572
- * tag: 'p',
573
- *
574
- * children: collection
575
- * } );
576
- * ```
577
- */
494
+ * A definition of the {@link module:ui/template~Template}. It describes what kind of
495
+ * node a template will render (HTML element or text), attributes of an element, DOM event
496
+ * listeners and children.
497
+ *
498
+ * Also see:
499
+ * * {@link module:ui/template~TemplateValueSchema} to learn about HTML element attributes,
500
+ * * {@link module:ui/template~TemplateListenerSchema} to learn about DOM event listeners.
501
+ *
502
+ * A sample definition on an HTML element can look like this:
503
+ *
504
+ * ```ts
505
+ * new Template( {
506
+ * tag: 'p',
507
+ * children: [
508
+ * {
509
+ * tag: 'span',
510
+ * attributes: { ... },
511
+ * children: [ ... ],
512
+ * },
513
+ * {
514
+ * text: 'static–text'
515
+ * },
516
+ * 'also-static–text',
517
+ * ],
518
+ * attributes: {
519
+ * class: {@link module:ui/template~TemplateValueSchema},
520
+ * id: {@link module:ui/template~TemplateValueSchema},
521
+ * style: {@link module:ui/template~TemplateValueSchema}
522
+ *
523
+ * // ...
524
+ * },
525
+ * on: {
526
+ * 'click': {@link module:ui/template~TemplateListenerSchema}
527
+ *
528
+ * // Document.querySelector format is also accepted.
529
+ * 'keyup@a.some-class': {@link module:ui/template~TemplateListenerSchema}
530
+ *
531
+ * // ...
532
+ * }
533
+ * } );
534
+ * ```
535
+ *
536
+ * A {@link module:ui/view~View}, another {@link module:ui/template~Template} or a native DOM node
537
+ * can also become a child of a template. When a view is passed, its {@link module:ui/view~View#element} is used:
538
+ *
539
+ * ```ts
540
+ * const view = new SomeView();
541
+ * const childTemplate = new Template( { ... } );
542
+ * const childNode = document.createElement( 'b' );
543
+ *
544
+ * new Template( {
545
+ * tag: 'p',
546
+ *
547
+ * children: [
548
+ * // view#element will be added as a child of this <p>.
549
+ * view,
550
+ *
551
+ * // The output of childTemplate.render() will be added here.
552
+ * childTemplate,
553
+ *
554
+ * // Native DOM nodes are included directly in the rendered output.
555
+ * childNode
556
+ * ]
557
+ * } );
558
+ * ```
559
+ *
560
+ * An entire {@link module:ui/viewcollection~ViewCollection} can be used as a child in the definition:
561
+ *
562
+ * ```ts
563
+ * const collection = new ViewCollection();
564
+ * collection.add( someView );
565
+ *
566
+ * new Template( {
567
+ * tag: 'p',
568
+ *
569
+ * children: collection
570
+ * } );
571
+ * ```
572
+ */
578
573
  export type TemplateDefinition = string | Template | TemplateElementDefinition | TemplateTextDefinition;
579
574
  export type TemplateElementDefinition = {
580
- /**
581
- * See the template {@link module:ui/template~Template#tag} property.
582
- */
583
- tag: string;
584
- /**
585
- * See the template {@link module:ui/template~Template#attributes} property.
586
- */
587
- attributes?: Record<string, TemplateValueSchema>;
588
- /**
589
- * See the template {@link module:ui/template~Template#children} property.
590
- */
591
- children?: Iterable<View | Node | Template | TemplateDefinition>;
592
- /**
593
- * See the template {@link module:ui/template~Template#eventListeners} property.
594
- */
595
- on?: Record<string, TemplateListenerSchema>;
575
+ /**
576
+ * See the template {@link module:ui/template~Template#tag} property.
577
+ */
578
+ tag: string;
579
+ /**
580
+ * See the template {@link module:ui/template~Template#attributes} property.
581
+ */
582
+ attributes?: Record<string, TemplateValueSchema>;
583
+ /**
584
+ * See the template {@link module:ui/template~Template#children} property.
585
+ */
586
+ children?: Iterable<View | Node | Template | TemplateDefinition>;
587
+ /**
588
+ * See the template {@link module:ui/template~Template#eventListeners} property.
589
+ */
590
+ on?: Record<string, TemplateListenerSchema>;
596
591
  };
597
592
  export type TemplateTextDefinition = {
598
- /**
599
- * See the template {@link module:ui/template~Template#text} property.
600
- */
601
- text: ArrayOrItem<TemplateSimpleValueSchema>;
593
+ /**
594
+ * See the template {@link module:ui/template~Template#text} property.
595
+ */
596
+ text: ArrayOrItem<TemplateSimpleValueSchema>;
602
597
  };
603
- export type FalsyValue = false | null | undefined | '';
598
+ export type FalsyValue = false | null | undefined | "";
604
599
  export type NamespacedValue<T> = {
605
- ns: string;
606
- value: T;
600
+ ns: string;
601
+ value: T;
607
602
  };
608
603
  export type TemplateSimpleValue = string | boolean | number | null | undefined;
609
604
  export type TemplateSimpleValueSchema = TemplateSimpleValue | AttributeBinding;
610
605
  /**
611
- * Describes a value of an HTML element attribute or `textContent`. It allows combining multiple
612
- * data sources like static values and {@link module:utils/observablemixin~Observable} attributes.
613
- *
614
- * Also see:
615
- * * {@link module:ui/template~TemplateDefinition} to learn where to use it,
616
- * * {@link module:ui/template~Template.bind} to learn how to configure
617
- * {@link module:utils/observablemixin~Observable} attribute bindings,
618
- * * {@link module:ui/template~Template#render} to learn how to render a template,
619
- * * {@link module:ui/template~BindChain#to `to()`} and {@link module:ui/template~BindChain#if `if()`}
620
- * methods to learn more about bindings.
621
- *
622
- * Attribute values can be described in many different ways:
623
- *
624
- * ```ts
625
- * // Bind helper will create bindings to attributes of the observable.
626
- * const bind = Template.bind( observable, emitter );
627
- *
628
- * new Template( {
629
- * tag: 'p',
630
- * attributes: {
631
- * // A plain string schema.
632
- * 'class': 'static-text',
633
- *
634
- * // An object schema, binds to the "foo" attribute of the
635
- * // observable and follows its value.
636
- * 'class': bind.to( 'foo' ),
637
- *
638
- * // An array schema, combines the above.
639
- * 'class': [
640
- * 'static-text',
641
- * bind.to( 'bar', () => { ... } ),
642
- *
643
- * // Bindings can also be conditional.
644
- * bind.if( 'baz', 'class-when-baz-is-true' )
645
- * ],
646
- *
647
- * // An array schema, with a custom namespace, e.g. useful for creating SVGs.
648
- * 'class': {
649
- * ns: 'http://ns.url',
650
- * value: [
651
- * bind.if( 'baz', 'value-when-true' ),
652
- * 'static-text'
653
- * ]
654
- * },
655
- *
656
- * // An object schema, specific for styles.
657
- * style: {
658
- * color: 'red',
659
- * '--color': 'red',
660
- * backgroundColor: bind.to( 'qux', () => { ... } )
661
- * }
662
- * }
663
- * } );
664
- * ```
665
- *
666
- * Text nodes can also have complex values:
667
- *
668
- * ```ts
669
- * const bind = Template.bind( observable, emitter );
670
- *
671
- * // Will render a "foo" text node.
672
- * new Template( {
673
- * text: 'foo'
674
- * } );
675
- *
676
- * // Will render a "static text: {observable.foo}" text node.
677
- * // The text of the node will be updated as the "foo" attribute changes.
678
- * new Template( {
679
- * text: [
680
- * 'static text: ',
681
- * bind.to( 'foo', () => { ... } )
682
- * ]
683
- * } );
684
- * ```
685
- */
606
+ * Describes a value of an HTML element attribute or `textContent`. It allows combining multiple
607
+ * data sources like static values and {@link module:utils/observablemixin~Observable} attributes.
608
+ *
609
+ * Also see:
610
+ * * {@link module:ui/template~TemplateDefinition} to learn where to use it,
611
+ * * {@link module:ui/template~Template.bind} to learn how to configure
612
+ * {@link module:utils/observablemixin~Observable} attribute bindings,
613
+ * * {@link module:ui/template~Template#render} to learn how to render a template,
614
+ * * {@link module:ui/template~BindChain#to `to()`} and {@link module:ui/template~BindChain#if `if()`}
615
+ * methods to learn more about bindings.
616
+ *
617
+ * Attribute values can be described in many different ways:
618
+ *
619
+ * ```ts
620
+ * // Bind helper will create bindings to attributes of the observable.
621
+ * const bind = Template.bind( observable, emitter );
622
+ *
623
+ * new Template( {
624
+ * tag: 'p',
625
+ * attributes: {
626
+ * // A plain string schema.
627
+ * 'class': 'static-text',
628
+ *
629
+ * // An object schema, binds to the "foo" attribute of the
630
+ * // observable and follows its value.
631
+ * 'class': bind.to( 'foo' ),
632
+ *
633
+ * // An array schema, combines the above.
634
+ * 'class': [
635
+ * 'static-text',
636
+ * bind.to( 'bar', () => { ... } ),
637
+ *
638
+ * // Bindings can also be conditional.
639
+ * bind.if( 'baz', 'class-when-baz-is-true' )
640
+ * ],
641
+ *
642
+ * // An array schema, with a custom namespace, e.g. useful for creating SVGs.
643
+ * 'class': {
644
+ * ns: 'http://ns.url',
645
+ * value: [
646
+ * bind.if( 'baz', 'value-when-true' ),
647
+ * 'static-text'
648
+ * ]
649
+ * },
650
+ *
651
+ * // An object schema, specific for styles.
652
+ * style: {
653
+ * color: 'red',
654
+ * '--color': 'red',
655
+ * backgroundColor: bind.to( 'qux', () => { ... } )
656
+ * }
657
+ * }
658
+ * } );
659
+ * ```
660
+ *
661
+ * Text nodes can also have complex values:
662
+ *
663
+ * ```ts
664
+ * const bind = Template.bind( observable, emitter );
665
+ *
666
+ * // Will render a "foo" text node.
667
+ * new Template( {
668
+ * text: 'foo'
669
+ * } );
670
+ *
671
+ * // Will render a "static text: {observable.foo}" text node.
672
+ * // The text of the node will be updated as the "foo" attribute changes.
673
+ * new Template( {
674
+ * text: [
675
+ * 'static text: ',
676
+ * bind.to( 'foo', () => { ... } )
677
+ * ]
678
+ * } );
679
+ * ```
680
+ */
686
681
  export type TemplateValueSchema = ArrayOrItem<TemplateSimpleValueSchema | NamespacedValue<TemplateSimpleValueSchema>> | Record<string, TemplateSimpleValueSchema>;
687
682
  /**
688
- * Describes an event listener attached to an HTML element. Such listener can propagate DOM events
689
- * through an {@link module:utils/observablemixin~Observable} instance, execute custom callbacks
690
- * or both, if necessary.
691
- *
692
- * Also see:
693
- * * {@link module:ui/template~TemplateDefinition} to learn more about template definitions,
694
- * * {@link module:ui/template~BindChain#to `to()`} method to learn more about bindings.
695
- *
696
- * Check out different ways of attaching event listeners below:
697
- *
698
- * ```ts
699
- * // Bind helper will propagate events through the observable.
700
- * const bind = Template.bind( observable, emitter );
701
- *
702
- * new Template( {
703
- * tag: 'p',
704
- * on: {
705
- * // An object schema. The observable will fire the "clicked" event upon DOM "click".
706
- * click: bind.to( 'clicked' )
707
- *
708
- * // An object schema. It will work for "click" event on "a.foo" children only.
709
- * 'click@a.foo': bind.to( 'clicked' )
710
- *
711
- * // An array schema, makes the observable propagate multiple events.
712
- * click: [
713
- * bind.to( 'clicked' ),
714
- * bind.to( 'executed' )
715
- * ],
716
- *
717
- * // An array schema with a custom callback.
718
- * 'click@a.foo': {
719
- * bind.to( 'clicked' ),
720
- * bind.to( evt => {
721
- * console.log( `${ evt.target } has been clicked!` );
722
- * } }
723
- * }
724
- * }
725
- * } );
726
- * ```
727
- */
683
+ * Describes an event listener attached to an HTML element. Such listener can propagate DOM events
684
+ * through an {@link module:utils/observablemixin~Observable} instance, execute custom callbacks
685
+ * or both, if necessary.
686
+ *
687
+ * Also see:
688
+ * * {@link module:ui/template~TemplateDefinition} to learn more about template definitions,
689
+ * * {@link module:ui/template~BindChain#to `to()`} method to learn more about bindings.
690
+ *
691
+ * Check out different ways of attaching event listeners below:
692
+ *
693
+ * ```ts
694
+ * // Bind helper will propagate events through the observable.
695
+ * const bind = Template.bind( observable, emitter );
696
+ *
697
+ * new Template( {
698
+ * tag: 'p',
699
+ * on: {
700
+ * // An object schema. The observable will fire the "clicked" event upon DOM "click".
701
+ * click: bind.to( 'clicked' )
702
+ *
703
+ * // An object schema. It will work for "click" event on "a.foo" children only.
704
+ * 'click@a.foo': bind.to( 'clicked' )
705
+ *
706
+ * // An array schema, makes the observable propagate multiple events.
707
+ * click: [
708
+ * bind.to( 'clicked' ),
709
+ * bind.to( 'executed' )
710
+ * ],
711
+ *
712
+ * // An array schema with a custom callback.
713
+ * 'click@a.foo': {
714
+ * bind.to( 'clicked' ),
715
+ * bind.to( evt => {
716
+ * console.log( `${ evt.target } has been clicked!` );
717
+ * } }
718
+ * }
719
+ * }
720
+ * } );
721
+ * ```
722
+ */
728
723
  export type TemplateListenerSchema = ArrayOrItem<ListenerBinding>;
729
724
  declare const AttributeBindingSymbol: unique symbol;
730
725
  declare const ListenerBindingSymbol: unique symbol;
731
726
  export interface AttributeBinding {
732
- _opaqueAttributeBinding: typeof AttributeBindingSymbol;
727
+ _opaqueAttributeBinding: typeof AttributeBindingSymbol;
733
728
  }
734
729
  export interface ListenerBinding {
735
- _opaqueListenerBinding: typeof ListenerBindingSymbol;
730
+ _opaqueListenerBinding: typeof ListenerBindingSymbol;
736
731
  }
737
732
  /**
738
- * The return value of {@link ~Template.bind `Template.bind()`}. It provides `to()` and `if()`
739
- * methods to create the {@link module:utils/observablemixin~Observable observable} attribute and event bindings.
740
- */
733
+ * The return value of {@link ~Template.bind `Template.bind()`}. It provides `to()` and `if()`
734
+ * methods to create the {@link module:utils/observablemixin~Observable observable} attribute and event bindings.
735
+ */
741
736
  export interface BindChain<TObservable> {
742
- /**
743
- * Binds an {@link module:utils/observablemixin~Observable observable} to either:
744
- *
745
- * * an HTML element attribute or a text node `textContent`, so it remains in sync with the observable
746
- * attribute as it changes,
747
- * * or an HTML element DOM event, so the DOM events are propagated through an observable.
748
- *
749
- * Some common use cases of `to()` bindings are presented below:
750
- *
751
- * ```ts
752
- * const bind = Template.bind( observable, emitter );
753
- *
754
- * new Template( {
755
- * tag: 'p',
756
- * attributes: {
757
- * // class="..." attribute gets bound to `observable#a`
758
- * class: bind.to( 'a' )
759
- * },
760
- * children: [
761
- * // <p>...</p> gets bound to observable#b; always `toUpperCase()`.
762
- * {
763
- * text: bind.to( 'b', ( value, node ) => value.toUpperCase() )
764
- * }
765
- * ],
766
- * on: {
767
- * click: [
768
- * // An observable will fire "clicked" upon "click" in the DOM.
769
- * bind.to( 'clicked' ),
770
- *
771
- * // A custom callback will be executed upon "click" in the DOM.
772
- * bind.to( () => {
773
- * ...
774
- * } )
775
- * ]
776
- * }
777
- * } ).render();
778
- * ```
779
- *
780
- * Learn more about using `to()` in the {@link module:ui/template~TemplateValueSchema} and
781
- * {@link module:ui/template~TemplateListenerSchema}.
782
- *
783
- * @label ATTRIBUTE
784
- * @param attribute An attribute name of {@link module:utils/observablemixin~Observable}.
785
- */
786
- to<TAttribute extends keyof TObservable & string>(attribute: TAttribute): AttributeBinding & ListenerBinding;
787
- /**
788
- * Binds an {@link module:utils/observablemixin~Observable observable} to either:
789
- *
790
- * * an HTML element attribute or a text node `textContent`, so it remains in sync with the observable
791
- * attribute as it changes,
792
- * * or an HTML element DOM event, so the DOM events are propagated through an observable.
793
- *
794
- * Some common use cases of `to()` bindings are presented below:
795
- *
796
- * ```ts
797
- * const bind = Template.bind( observable, emitter );
798
- *
799
- * new Template( {
800
- * tag: 'p',
801
- * attributes: {
802
- * // class="..." attribute gets bound to `observable#a`
803
- * class: bind.to( 'a' )
804
- * },
805
- * children: [
806
- * // <p>...</p> gets bound to observable#b; always `toUpperCase()`.
807
- * {
808
- * text: bind.to( 'b', ( value, node ) => value.toUpperCase() )
809
- * }
810
- * ],
811
- * on: {
812
- * click: [
813
- * // An observable will fire "clicked" upon "click" in the DOM.
814
- * bind.to( 'clicked' ),
815
- *
816
- * // A custom callback will be executed upon "click" in the DOM.
817
- * bind.to( () => {
818
- * ...
819
- * } )
820
- * ]
821
- * }
822
- * } ).render();
823
- * ```
824
- *
825
- * Learn more about using `to()` in the {@link module:ui/template~TemplateValueSchema} and
826
- * {@link module:ui/template~TemplateListenerSchema}.
827
- *
828
- * @label ATTRIBUTE_CALLBACK
829
- * @param attribute An attribute name of {@link module:utils/observablemixin~Observable}.
830
- * @param callback Allows for processing of the value. Accepts `Node` and `value` as arguments.
831
- */
832
- to<TAttribute extends keyof TObservable & string>(attribute: TAttribute, callback: (value: TObservable[TAttribute], node: Node) => (TemplateSimpleValue)): AttributeBinding;
833
- /**
834
- * Binds an {@link module:utils/observablemixin~Observable observable} to either:
835
- *
836
- * * an HTML element attribute or a text node `textContent`, so it remains in sync with the observable
837
- * attribute as it changes,
838
- * * or an HTML element DOM event, so the DOM events are propagated through an observable.
839
- *
840
- * Some common use cases of `to()` bindings are presented below:
841
- *
842
- * ```ts
843
- * const bind = Template.bind( observable, emitter );
844
- *
845
- * new Template( {
846
- * tag: 'p',
847
- * attributes: {
848
- * // class="..." attribute gets bound to `observable#a`
849
- * class: bind.to( 'a' )
850
- * },
851
- * children: [
852
- * // <p>...</p> gets bound to observable#b; always `toUpperCase()`.
853
- * {
854
- * text: bind.to( 'b', ( value, node ) => value.toUpperCase() )
855
- * }
856
- * ],
857
- * on: {
858
- * click: [
859
- * // An observable will fire "clicked" upon "click" in the DOM.
860
- * bind.to( 'clicked' ),
861
- *
862
- * // A custom callback will be executed upon "click" in the DOM.
863
- * bind.to( () => {
864
- * ...
865
- * } )
866
- * ]
867
- * }
868
- * } ).render();
869
- * ```
870
- *
871
- * Learn more about using `to()` in the {@link module:ui/template~TemplateValueSchema} and
872
- * {@link module:ui/template~TemplateListenerSchema}.
873
- *
874
- * @label EVENT
875
- * @param eventNameOrCallback A DOM event name or an event callback.
876
- */
877
- to(eventNameOrCallback: string | ((domEvent: Event) => void)): ListenerBinding;
878
- /**
879
- * Binds an {@link module:utils/observablemixin~Observable observable} to an HTML element attribute or a text
880
- * node `textContent` so it remains in sync with the observable attribute as it changes.
881
- *
882
- * Unlike {@link module:ui/template~BindChain#to}, it controls the presence of the attribute or `textContent`
883
- * depending on the "falseness" of an {@link module:utils/observablemixin~Observable} attribute.
884
- *
885
- * ```ts
886
- * const bind = Template.bind( observable, emitter );
887
- *
888
- * new Template( {
889
- * tag: 'input',
890
- * attributes: {
891
- * // <input checked> when `observable#a` is not undefined/null/false/''
892
- * // <input> when `observable#a` is undefined/null/false
893
- * checked: bind.if( 'a' )
894
- * },
895
- * children: [
896
- * {
897
- * // <input>"b-is-not-set"</input> when `observable#b` is undefined/null/false/''
898
- * // <input></input> when `observable#b` is not "falsy"
899
- * text: bind.if( 'b', 'b-is-not-set', ( value, node ) => !value )
900
- * }
901
- * ]
902
- * } ).render();
903
- * ```
904
- *
905
- * Learn more about using `if()` in the {@link module:ui/template~TemplateValueSchema}.
906
- *
907
- * @param attribute An attribute name of {@link module:utils/observablemixin~Observable} used in the binding.
908
- * @param valueIfTrue Value set when the {@link module:utils/observablemixin~Observable} attribute is not
909
- * undefined/null/false/'' (empty string).
910
- * @param callback Allows for processing of the value. Accepts `Node` and `value` as arguments.
911
- */
912
- if<TAttribute extends keyof TObservable & string>(attribute: TAttribute, valueIfTrue?: unknown, callback?: (value: TObservable[TAttribute], node: Node) => (boolean | FalsyValue)): AttributeBinding;
737
+ /**
738
+ * Binds an {@link module:utils/observablemixin~Observable observable} to either:
739
+ *
740
+ * * an HTML element attribute or a text node `textContent`, so it remains in sync with the observable
741
+ * attribute as it changes,
742
+ * * or an HTML element DOM event, so the DOM events are propagated through an observable.
743
+ *
744
+ * Some common use cases of `to()` bindings are presented below:
745
+ *
746
+ * ```ts
747
+ * const bind = Template.bind( observable, emitter );
748
+ *
749
+ * new Template( {
750
+ * tag: 'p',
751
+ * attributes: {
752
+ * // class="..." attribute gets bound to `observable#a`
753
+ * class: bind.to( 'a' )
754
+ * },
755
+ * children: [
756
+ * // <p>...</p> gets bound to observable#b; always `toUpperCase()`.
757
+ * {
758
+ * text: bind.to( 'b', ( value, node ) => value.toUpperCase() )
759
+ * }
760
+ * ],
761
+ * on: {
762
+ * click: [
763
+ * // An observable will fire "clicked" upon "click" in the DOM.
764
+ * bind.to( 'clicked' ),
765
+ *
766
+ * // A custom callback will be executed upon "click" in the DOM.
767
+ * bind.to( () => {
768
+ * ...
769
+ * } )
770
+ * ]
771
+ * }
772
+ * } ).render();
773
+ * ```
774
+ *
775
+ * Learn more about using `to()` in the {@link module:ui/template~TemplateValueSchema} and
776
+ * {@link module:ui/template~TemplateListenerSchema}.
777
+ *
778
+ * @label ATTRIBUTE
779
+ * @param attribute An attribute name of {@link module:utils/observablemixin~Observable}.
780
+ */
781
+ to<TAttribute extends keyof TObservable & string>(attribute: TAttribute): AttributeBinding & ListenerBinding;
782
+ /**
783
+ * Binds an {@link module:utils/observablemixin~Observable observable} to either:
784
+ *
785
+ * * an HTML element attribute or a text node `textContent`, so it remains in sync with the observable
786
+ * attribute as it changes,
787
+ * * or an HTML element DOM event, so the DOM events are propagated through an observable.
788
+ *
789
+ * Some common use cases of `to()` bindings are presented below:
790
+ *
791
+ * ```ts
792
+ * const bind = Template.bind( observable, emitter );
793
+ *
794
+ * new Template( {
795
+ * tag: 'p',
796
+ * attributes: {
797
+ * // class="..." attribute gets bound to `observable#a`
798
+ * class: bind.to( 'a' )
799
+ * },
800
+ * children: [
801
+ * // <p>...</p> gets bound to observable#b; always `toUpperCase()`.
802
+ * {
803
+ * text: bind.to( 'b', ( value, node ) => value.toUpperCase() )
804
+ * }
805
+ * ],
806
+ * on: {
807
+ * click: [
808
+ * // An observable will fire "clicked" upon "click" in the DOM.
809
+ * bind.to( 'clicked' ),
810
+ *
811
+ * // A custom callback will be executed upon "click" in the DOM.
812
+ * bind.to( () => {
813
+ * ...
814
+ * } )
815
+ * ]
816
+ * }
817
+ * } ).render();
818
+ * ```
819
+ *
820
+ * Learn more about using `to()` in the {@link module:ui/template~TemplateValueSchema} and
821
+ * {@link module:ui/template~TemplateListenerSchema}.
822
+ *
823
+ * @label ATTRIBUTE_CALLBACK
824
+ * @param attribute An attribute name of {@link module:utils/observablemixin~Observable}.
825
+ * @param callback Allows for processing of the value. Accepts `Node` and `value` as arguments.
826
+ */
827
+ to<TAttribute extends keyof TObservable & string>(attribute: TAttribute, callback: (value: TObservable[TAttribute], node: Node) => (TemplateSimpleValue)): AttributeBinding;
828
+ /**
829
+ * Binds an {@link module:utils/observablemixin~Observable observable} to either:
830
+ *
831
+ * * an HTML element attribute or a text node `textContent`, so it remains in sync with the observable
832
+ * attribute as it changes,
833
+ * * or an HTML element DOM event, so the DOM events are propagated through an observable.
834
+ *
835
+ * Some common use cases of `to()` bindings are presented below:
836
+ *
837
+ * ```ts
838
+ * const bind = Template.bind( observable, emitter );
839
+ *
840
+ * new Template( {
841
+ * tag: 'p',
842
+ * attributes: {
843
+ * // class="..." attribute gets bound to `observable#a`
844
+ * class: bind.to( 'a' )
845
+ * },
846
+ * children: [
847
+ * // <p>...</p> gets bound to observable#b; always `toUpperCase()`.
848
+ * {
849
+ * text: bind.to( 'b', ( value, node ) => value.toUpperCase() )
850
+ * }
851
+ * ],
852
+ * on: {
853
+ * click: [
854
+ * // An observable will fire "clicked" upon "click" in the DOM.
855
+ * bind.to( 'clicked' ),
856
+ *
857
+ * // A custom callback will be executed upon "click" in the DOM.
858
+ * bind.to( () => {
859
+ * ...
860
+ * } )
861
+ * ]
862
+ * }
863
+ * } ).render();
864
+ * ```
865
+ *
866
+ * Learn more about using `to()` in the {@link module:ui/template~TemplateValueSchema} and
867
+ * {@link module:ui/template~TemplateListenerSchema}.
868
+ *
869
+ * @label EVENT
870
+ * @param eventNameOrCallback A DOM event name or an event callback.
871
+ */
872
+ to(eventNameOrCallback: string | ((domEvent: Event) => void)): ListenerBinding;
873
+ /**
874
+ * Binds an {@link module:utils/observablemixin~Observable observable} to an HTML element attribute or a text
875
+ * node `textContent` so it remains in sync with the observable attribute as it changes.
876
+ *
877
+ * Unlike {@link module:ui/template~BindChain#to}, it controls the presence of the attribute or `textContent`
878
+ * depending on the "falseness" of an {@link module:utils/observablemixin~Observable} attribute.
879
+ *
880
+ * ```ts
881
+ * const bind = Template.bind( observable, emitter );
882
+ *
883
+ * new Template( {
884
+ * tag: 'input',
885
+ * attributes: {
886
+ * // <input checked> when `observable#a` is not undefined/null/false/''
887
+ * // <input> when `observable#a` is undefined/null/false
888
+ * checked: bind.if( 'a' )
889
+ * },
890
+ * children: [
891
+ * {
892
+ * // <input>"b-is-not-set"</input> when `observable#b` is undefined/null/false/''
893
+ * // <input></input> when `observable#b` is not "falsy"
894
+ * text: bind.if( 'b', 'b-is-not-set', ( value, node ) => !value )
895
+ * }
896
+ * ]
897
+ * } ).render();
898
+ * ```
899
+ *
900
+ * Learn more about using `if()` in the {@link module:ui/template~TemplateValueSchema}.
901
+ *
902
+ * @param attribute An attribute name of {@link module:utils/observablemixin~Observable} used in the binding.
903
+ * @param valueIfTrue Value set when the {@link module:utils/observablemixin~Observable} attribute is not
904
+ * undefined/null/false/'' (empty string).
905
+ * @param callback Allows for processing of the value. Accepts `Node` and `value` as arguments.
906
+ */
907
+ if<TAttribute extends keyof TObservable & string>(attribute: TAttribute, valueIfTrue?: unknown, callback?: (value: TObservable[TAttribute], node: Node) => (boolean | FalsyValue)): AttributeBinding;
913
908
  }
914
909
  /**
915
- * The {@link module:ui/template~Template#_renderNode} configuration.
916
- * @internal
917
- */
910
+ * The {@link module:ui/template~Template#_renderNode} configuration.
911
+ * @internal
912
+ */
918
913
  export interface RenderData {
919
- /**
920
- * A node which is being rendered.
921
- */
922
- node: HTMLElement | Text;
923
- /**
924
- * Tells {@link module:ui/template~Template#_renderNode} to render
925
- * children into `DocumentFragment` first and then append the fragment
926
- * to the parent element. It is a speed optimization.
927
- */
928
- intoFragment: boolean;
929
- /**
930
- * Indicates whether the {@link #node} has been provided by {@link module:ui/template~Template#apply}.
931
- */
932
- isApplying: boolean;
933
- /**
934
- * An object storing the data that helps {@link module:ui/template~Template#revert}
935
- * bringing back an element to its initial state, i.e. before
936
- * {@link module:ui/template~Template#apply} was called.
937
- */
938
- revertData?: RevertData;
914
+ /**
915
+ * A node which is being rendered.
916
+ */
917
+ node: HTMLElement | Text;
918
+ /**
919
+ * Tells {@link module:ui/template~Template#_renderNode} to render
920
+ * children into `DocumentFragment` first and then append the fragment
921
+ * to the parent element. It is a speed optimization.
922
+ */
923
+ intoFragment: boolean;
924
+ /**
925
+ * Indicates whether the {@link #node} has been provided by {@link module:ui/template~Template#apply}.
926
+ */
927
+ isApplying: boolean;
928
+ /**
929
+ * An object storing the data that helps {@link module:ui/template~Template#revert}
930
+ * bringing back an element to its initial state, i.e. before
931
+ * {@link module:ui/template~Template#apply} was called.
932
+ */
933
+ revertData?: RevertData;
939
934
  }
940
935
  interface RevertData {
941
- text?: string | null;
942
- children: Array<RevertData>;
943
- bindings: Array<Array<() => void>>;
944
- attributes: Record<string, string | null>;
936
+ text?: string | null;
937
+ children: Array<RevertData>;
938
+ bindings: Array<Array<() => void>>;
939
+ attributes: Record<string, string | null>;
945
940
  }
946
941
  export {};