@ckeditor/ckeditor5-ui 39.0.1 → 40.0.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 (229) hide show
  1. package/CHANGELOG.md +1 -1
  2. package/LICENSE.md +1 -1
  3. package/README.md +4 -4
  4. package/lang/contexts.json +5 -1
  5. package/lang/translations/ar.po +17 -0
  6. package/lang/translations/ast.po +17 -0
  7. package/lang/translations/az.po +17 -0
  8. package/lang/translations/bg.po +17 -0
  9. package/lang/translations/bn.po +17 -0
  10. package/lang/translations/ca.po +17 -0
  11. package/lang/translations/cs.po +17 -0
  12. package/lang/translations/da.po +17 -0
  13. package/lang/translations/de-ch.po +17 -0
  14. package/lang/translations/de.po +17 -0
  15. package/lang/translations/el.po +17 -0
  16. package/lang/translations/en-au.po +17 -0
  17. package/lang/translations/en-gb.po +17 -0
  18. package/lang/translations/en.po +17 -0
  19. package/lang/translations/eo.po +17 -0
  20. package/lang/translations/es.po +17 -0
  21. package/lang/translations/et.po +17 -0
  22. package/lang/translations/eu.po +17 -0
  23. package/lang/translations/fa.po +17 -0
  24. package/lang/translations/fi.po +17 -0
  25. package/lang/translations/fr.po +17 -0
  26. package/lang/translations/gl.po +17 -0
  27. package/lang/translations/he.po +17 -0
  28. package/lang/translations/hi.po +17 -0
  29. package/lang/translations/hr.po +17 -0
  30. package/lang/translations/hu.po +17 -0
  31. package/lang/translations/id.po +17 -0
  32. package/lang/translations/it.po +17 -0
  33. package/lang/translations/ja.po +17 -0
  34. package/lang/translations/km.po +17 -0
  35. package/lang/translations/kn.po +17 -0
  36. package/lang/translations/ko.po +17 -0
  37. package/lang/translations/ku.po +17 -0
  38. package/lang/translations/lt.po +17 -0
  39. package/lang/translations/lv.po +17 -0
  40. package/lang/translations/ms.po +17 -0
  41. package/lang/translations/nb.po +17 -0
  42. package/lang/translations/ne.po +17 -0
  43. package/lang/translations/nl.po +17 -0
  44. package/lang/translations/no.po +17 -0
  45. package/lang/translations/pl.po +17 -0
  46. package/lang/translations/pt-br.po +17 -0
  47. package/lang/translations/pt.po +17 -0
  48. package/lang/translations/ro.po +17 -0
  49. package/lang/translations/ru.po +17 -0
  50. package/lang/translations/sk.po +17 -0
  51. package/lang/translations/sl.po +17 -0
  52. package/lang/translations/sq.po +17 -0
  53. package/lang/translations/sr-latn.po +17 -0
  54. package/lang/translations/sr.po +17 -0
  55. package/lang/translations/sv.po +17 -0
  56. package/lang/translations/th.po +17 -0
  57. package/lang/translations/tk.po +17 -0
  58. package/lang/translations/tr.po +17 -0
  59. package/lang/translations/tt.po +17 -0
  60. package/lang/translations/ug.po +17 -0
  61. package/lang/translations/uk.po +17 -0
  62. package/lang/translations/ur.po +17 -0
  63. package/lang/translations/uz.po +17 -0
  64. package/lang/translations/vi.po +17 -0
  65. package/lang/translations/zh-cn.po +17 -0
  66. package/lang/translations/zh.po +17 -0
  67. package/package.json +3 -7
  68. package/src/augmentation.d.ts +86 -86
  69. package/src/augmentation.js +5 -5
  70. package/src/autocomplete/autocompleteview.d.ts +81 -0
  71. package/src/autocomplete/autocompleteview.js +146 -0
  72. package/src/bindings/addkeyboardhandlingforgrid.d.ts +27 -27
  73. package/src/bindings/addkeyboardhandlingforgrid.js +107 -107
  74. package/src/bindings/clickoutsidehandler.d.ts +28 -28
  75. package/src/bindings/clickoutsidehandler.js +36 -36
  76. package/src/bindings/csstransitiondisablermixin.d.ts +40 -40
  77. package/src/bindings/csstransitiondisablermixin.js +55 -55
  78. package/src/bindings/injectcsstransitiondisabler.d.ts +59 -59
  79. package/src/bindings/injectcsstransitiondisabler.js +71 -71
  80. package/src/bindings/preventdefault.d.ts +33 -33
  81. package/src/bindings/preventdefault.js +34 -34
  82. package/src/bindings/submithandler.d.ts +57 -57
  83. package/src/bindings/submithandler.js +47 -47
  84. package/src/button/button.d.ts +178 -178
  85. package/src/button/button.js +5 -5
  86. package/src/button/buttonlabel.d.ts +34 -0
  87. package/src/button/buttonlabel.js +5 -0
  88. package/src/button/buttonlabelview.d.ts +31 -0
  89. package/src/button/buttonlabelview.js +42 -0
  90. package/src/button/buttonview.d.ts +185 -177
  91. package/src/button/buttonview.js +219 -231
  92. package/src/button/switchbuttonview.d.ts +45 -45
  93. package/src/button/switchbuttonview.js +75 -75
  94. package/src/colorgrid/colorgridview.d.ts +132 -132
  95. package/src/colorgrid/colorgridview.js +124 -124
  96. package/src/colorgrid/colortileview.d.ts +28 -28
  97. package/src/colorgrid/colortileview.js +40 -40
  98. package/src/colorgrid/utils.d.ts +47 -47
  99. package/src/colorgrid/utils.js +84 -84
  100. package/src/colorpicker/colorpickerview.d.ts +137 -137
  101. package/src/colorpicker/colorpickerview.js +270 -270
  102. package/src/colorpicker/utils.d.ts +43 -43
  103. package/src/colorpicker/utils.js +99 -99
  104. package/src/colorselector/colorgridsfragmentview.d.ts +194 -194
  105. package/src/colorselector/colorgridsfragmentview.js +289 -289
  106. package/src/colorselector/colorpickerfragmentview.d.ts +128 -128
  107. package/src/colorselector/colorpickerfragmentview.js +205 -205
  108. package/src/colorselector/colorselectorview.d.ts +242 -242
  109. package/src/colorselector/colorselectorview.js +256 -256
  110. package/src/colorselector/documentcolorcollection.d.ts +70 -70
  111. package/src/colorselector/documentcolorcollection.js +42 -42
  112. package/src/componentfactory.d.ts +81 -81
  113. package/src/componentfactory.js +104 -104
  114. package/src/dropdown/button/dropdownbutton.d.ts +25 -25
  115. package/src/dropdown/button/dropdownbutton.js +5 -5
  116. package/src/dropdown/button/dropdownbuttonview.d.ts +48 -48
  117. package/src/dropdown/button/dropdownbuttonview.js +66 -66
  118. package/src/dropdown/button/splitbuttonview.d.ts +161 -161
  119. package/src/dropdown/button/splitbuttonview.js +152 -152
  120. package/src/dropdown/dropdownpanelfocusable.d.ts +21 -21
  121. package/src/dropdown/dropdownpanelfocusable.js +5 -5
  122. package/src/dropdown/dropdownpanelview.d.ts +62 -62
  123. package/src/dropdown/dropdownpanelview.js +97 -97
  124. package/src/dropdown/dropdownview.d.ts +315 -315
  125. package/src/dropdown/dropdownview.js +379 -378
  126. package/src/dropdown/utils.d.ts +235 -221
  127. package/src/dropdown/utils.js +458 -437
  128. package/src/editableui/editableuiview.d.ts +72 -72
  129. package/src/editableui/editableuiview.js +112 -112
  130. package/src/editableui/inline/inlineeditableuiview.d.ts +40 -40
  131. package/src/editableui/inline/inlineeditableuiview.js +48 -48
  132. package/src/editorui/bodycollection.d.ts +55 -55
  133. package/src/editorui/bodycollection.js +84 -84
  134. package/src/editorui/boxed/boxededitoruiview.d.ts +40 -40
  135. package/src/editorui/boxed/boxededitoruiview.js +81 -81
  136. package/src/editorui/editorui.d.ts +282 -282
  137. package/src/editorui/editorui.js +410 -410
  138. package/src/editorui/editoruiview.d.ts +39 -39
  139. package/src/editorui/editoruiview.js +38 -38
  140. package/src/editorui/poweredby.d.ts +71 -71
  141. package/src/editorui/poweredby.js +276 -299
  142. package/src/focuscycler.d.ts +226 -183
  143. package/src/focuscycler.js +245 -220
  144. package/src/formheader/formheaderview.d.ts +59 -53
  145. package/src/formheader/formheaderview.js +69 -63
  146. package/src/highlightedtext/highlightedtextview.d.ts +38 -0
  147. package/src/highlightedtext/highlightedtextview.js +102 -0
  148. package/src/icon/iconview.d.ts +85 -78
  149. package/src/icon/iconview.js +114 -112
  150. package/src/iframe/iframeview.d.ts +50 -50
  151. package/src/iframe/iframeview.js +63 -63
  152. package/src/index.d.ts +73 -63
  153. package/src/index.js +70 -62
  154. package/src/input/inputbase.d.ts +107 -0
  155. package/src/input/inputbase.js +110 -0
  156. package/src/input/inputview.d.ts +36 -121
  157. package/src/input/inputview.js +24 -106
  158. package/src/inputnumber/inputnumberview.d.ts +49 -49
  159. package/src/inputnumber/inputnumberview.js +40 -40
  160. package/src/inputtext/inputtextview.d.ts +18 -18
  161. package/src/inputtext/inputtextview.js +27 -27
  162. package/src/label/labelview.d.ts +36 -36
  163. package/src/label/labelview.js +41 -41
  164. package/src/labeledfield/labeledfieldview.d.ts +187 -182
  165. package/src/labeledfield/labeledfieldview.js +157 -157
  166. package/src/labeledfield/utils.d.ts +123 -93
  167. package/src/labeledfield/utils.js +176 -131
  168. package/src/labeledinput/labeledinputview.d.ts +125 -125
  169. package/src/labeledinput/labeledinputview.js +125 -125
  170. package/src/list/listitemgroupview.d.ts +51 -0
  171. package/src/list/listitemgroupview.js +75 -0
  172. package/src/list/listitemview.d.ts +36 -35
  173. package/src/list/listitemview.js +42 -40
  174. package/src/list/listseparatorview.d.ts +18 -18
  175. package/src/list/listseparatorview.js +28 -28
  176. package/src/list/listview.d.ts +122 -65
  177. package/src/list/listview.js +187 -90
  178. package/src/model.d.ts +22 -22
  179. package/src/model.js +31 -31
  180. package/src/notification/notification.d.ts +211 -211
  181. package/src/notification/notification.js +187 -187
  182. package/src/panel/balloon/balloonpanelview.d.ts +685 -685
  183. package/src/panel/balloon/balloonpanelview.js +1010 -988
  184. package/src/panel/balloon/contextualballoon.d.ts +299 -299
  185. package/src/panel/balloon/contextualballoon.js +572 -572
  186. package/src/panel/sticky/stickypanelview.d.ts +156 -158
  187. package/src/panel/sticky/stickypanelview.js +234 -231
  188. package/src/search/filteredview.d.ts +31 -0
  189. package/src/search/filteredview.js +5 -0
  190. package/src/search/searchinfoview.d.ts +45 -0
  191. package/src/search/searchinfoview.js +59 -0
  192. package/src/search/searchresultsview.d.ts +54 -0
  193. package/src/search/searchresultsview.js +65 -0
  194. package/src/search/text/searchtextqueryview.d.ts +76 -0
  195. package/src/search/text/searchtextqueryview.js +75 -0
  196. package/src/search/text/searchtextview.d.ts +219 -0
  197. package/src/search/text/searchtextview.js +201 -0
  198. package/src/spinner/spinnerview.d.ts +25 -0
  199. package/src/spinner/spinnerview.js +38 -0
  200. package/src/template.d.ts +942 -942
  201. package/src/template.js +1294 -1294
  202. package/src/textarea/textareaview.d.ts +88 -0
  203. package/src/textarea/textareaview.js +140 -0
  204. package/src/toolbar/balloon/balloontoolbar.d.ts +122 -122
  205. package/src/toolbar/balloon/balloontoolbar.js +300 -300
  206. package/src/toolbar/block/blockbuttonview.d.ts +35 -35
  207. package/src/toolbar/block/blockbuttonview.js +41 -41
  208. package/src/toolbar/block/blocktoolbar.d.ts +161 -161
  209. package/src/toolbar/block/blocktoolbar.js +395 -391
  210. package/src/toolbar/normalizetoolbarconfig.d.ts +40 -39
  211. package/src/toolbar/normalizetoolbarconfig.js +51 -51
  212. package/src/toolbar/toolbarlinebreakview.d.ts +18 -18
  213. package/src/toolbar/toolbarlinebreakview.js +28 -28
  214. package/src/toolbar/toolbarseparatorview.d.ts +18 -18
  215. package/src/toolbar/toolbarseparatorview.js +28 -28
  216. package/src/toolbar/toolbarview.d.ts +266 -265
  217. package/src/toolbar/toolbarview.js +719 -717
  218. package/src/tooltipmanager.d.ts +180 -180
  219. package/src/tooltipmanager.js +353 -353
  220. package/src/view.d.ts +422 -422
  221. package/src/view.js +396 -396
  222. package/src/viewcollection.d.ts +139 -139
  223. package/src/viewcollection.js +206 -206
  224. package/theme/components/autocomplete/autocomplete.css +22 -0
  225. package/theme/components/formheader/formheader.css +8 -0
  226. package/theme/components/highlightedtext/highlightedtext.css +12 -0
  227. package/theme/components/search/search.css +43 -0
  228. package/theme/components/spinner/spinner.css +23 -0
  229. package/theme/components/textarea/textarea.css +10 -0
package/src/view.d.ts CHANGED
@@ -1,422 +1,422 @@
1
- /**
2
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
3
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
4
- */
5
- /**
6
- * @module ui/view
7
- */
8
- import ViewCollection from './viewcollection';
9
- import Template, { type BindChain, type TemplateDefinition } from './template';
10
- import { Collection, type DecoratedMethodEvent, type Locale, type LocaleTranslate } from '@ckeditor/ckeditor5-utils';
11
- import '../theme/globals/globals.css';
12
- declare const View_base: import("@ckeditor/ckeditor5-utils").Mixed<{
13
- new (): import("@ckeditor/ckeditor5-utils").Observable;
14
- prototype: import("@ckeditor/ckeditor5-utils").Observable;
15
- }, import("@ckeditor/ckeditor5-utils").DomEmitter>;
16
- /**
17
- * The basic view class, which represents an HTML element created out of a
18
- * {@link module:ui/view~View#template}. Views are building blocks of the user interface and handle
19
- * interaction
20
- *
21
- * Views {@link module:ui/view~View#registerChild aggregate} children in
22
- * {@link module:ui/view~View#createCollection collections} and manage the life cycle of DOM
23
- * listeners e.g. by handling rendering and destruction.
24
- *
25
- * See the {@link module:ui/template~TemplateDefinition} syntax to learn more about shaping view
26
- * elements, attributes and listeners.
27
- *
28
- * ```ts
29
- * class SampleView extends View {
30
- * constructor( locale ) {
31
- * super( locale );
32
- *
33
- * const bind = this.bindTemplate;
34
- *
35
- * // Views define their interface (state) using observable attributes.
36
- * this.set( 'elementClass', 'bar' );
37
- *
38
- * this.setTemplate( {
39
- * tag: 'p',
40
- *
41
- * // The element of the view can be defined with its children.
42
- * children: [
43
- * 'Hello',
44
- * {
45
- * tag: 'b',
46
- * children: [ 'world!' ]
47
- * }
48
- * ],
49
- * attributes: {
50
- * class: [
51
- * 'foo',
52
- *
53
- * // Observable attributes control the state of the view in DOM.
54
- * bind.to( 'elementClass' )
55
- * ]
56
- * },
57
- * on: {
58
- * // Views listen to DOM events and propagate them.
59
- * click: bind.to( 'clicked' )
60
- * }
61
- * } );
62
- * }
63
- * }
64
- *
65
- * const view = new SampleView( locale );
66
- *
67
- * view.render();
68
- *
69
- * // Append <p class="foo bar">Hello<b>world</b></p> to the <body>
70
- * document.body.appendChild( view.element );
71
- *
72
- * // Change the class attribute to <p class="foo baz">Hello<b>world</b></p>
73
- * view.elementClass = 'baz';
74
- *
75
- * // Respond to the "click" event in DOM by executing a custom action.
76
- * view.on( 'clicked', () => {
77
- * console.log( 'The view has been clicked!' );
78
- * } );
79
- * ```
80
- */
81
- export default class View<TElement extends HTMLElement = HTMLElement> extends View_base {
82
- /**
83
- * An HTML element of the view. `null` until {@link #render rendered}
84
- * from the {@link #template}.
85
- *
86
- * ```ts
87
- * class SampleView extends View {
88
- * constructor() {
89
- * super();
90
- *
91
- * // A template instance the #element will be created from.
92
- * this.setTemplate( {
93
- * tag: 'p'
94
- *
95
- * // ...
96
- * } );
97
- * }
98
- * }
99
- *
100
- * const view = new SampleView();
101
- *
102
- * // Renders the #template.
103
- * view.render();
104
- *
105
- * // Append the HTML element of the view to <body>.
106
- * document.body.appendChild( view.element );
107
- * ```
108
- *
109
- * **Note**: The element of the view can also be assigned directly:
110
- *
111
- * ```ts
112
- * view.element = document.querySelector( '#my-container' );
113
- * ```
114
- */
115
- element: TElement | null;
116
- /**
117
- * Set `true` when the view has already been {@link module:ui/view~View#render rendered}.
118
- *
119
- * @readonly
120
- */
121
- isRendered: boolean;
122
- /**
123
- * A set of tools to localize the user interface.
124
- *
125
- * Also see {@link module:core/editor/editor~Editor#locale}.
126
- *
127
- * @readonly
128
- */
129
- locale: Locale | undefined;
130
- /**
131
- * Shorthand for {@link module:utils/locale~Locale#t}.
132
- *
133
- * Note: If {@link #locale} instance hasn't been passed to the view this method may not
134
- * be available.
135
- *
136
- * @see module:utils/locale~Locale#t
137
- */
138
- t: LocaleTranslate | undefined;
139
- /**
140
- * Template of this view. It provides the {@link #element} representing
141
- * the view in DOM, which is {@link #render rendered}.
142
- */
143
- template?: Template;
144
- viewUid?: string;
145
- /**
146
- * Collections registered with {@link #createCollection}.
147
- */
148
- protected _viewCollections: Collection<ViewCollection>;
149
- /**
150
- * A collection of view instances, which have been added directly
151
- * into the {@link module:ui/template~Template#children}.
152
- */
153
- protected _unboundChildren: ViewCollection;
154
- /**
155
- * Cached {@link module:ui/template~BindChain bind chain} object created by the
156
- * {@link #template}. See {@link #bindTemplate}.
157
- */
158
- private _bindTemplate?;
159
- /**
160
- * Creates an instance of the {@link module:ui/view~View} class.
161
- *
162
- * Also see {@link #render}.
163
- *
164
- * @param locale The localization services instance.
165
- */
166
- constructor(locale?: Locale);
167
- /**
168
- * Shorthand for {@link module:ui/template~Template.bind}, a binding
169
- * {@link module:ui/template~BindChain interface} pre–configured for the view instance.
170
- *
171
- * It provides {@link module:ui/template~BindChain#to `to()`} and
172
- * {@link module:ui/template~BindChain#if `if()`} methods that initialize bindings with
173
- * observable attributes and attach DOM listeners.
174
- *
175
- * ```ts
176
- * class SampleView extends View {
177
- * constructor( locale ) {
178
- * super( locale );
179
- *
180
- * const bind = this.bindTemplate;
181
- *
182
- * // These {@link module:utils/observablemixin~Observable observable} attributes will control
183
- * // the state of the view in DOM.
184
- * this.set( {
185
- * elementClass: 'foo',
186
- * isEnabled: true
187
- * } );
188
- *
189
- * this.setTemplate( {
190
- * tag: 'p',
191
- *
192
- * attributes: {
193
- * // The class HTML attribute will follow elementClass
194
- * // and isEnabled view attributes.
195
- * class: [
196
- * bind.to( 'elementClass' )
197
- * bind.if( 'isEnabled', 'present-when-enabled' )
198
- * ]
199
- * },
200
- *
201
- * on: {
202
- * // The view will fire the "clicked" event upon clicking <p> in DOM.
203
- * click: bind.to( 'clicked' )
204
- * }
205
- * } );
206
- * }
207
- * }
208
- * ```
209
- */
210
- get bindTemplate(): BindChain<this>;
211
- /**
212
- * Creates a new collection of views, which can be used as
213
- * {@link module:ui/template~Template#children} of this view.
214
- *
215
- * ```ts
216
- * class SampleView extends View {
217
- * constructor( locale ) {
218
- * super( locale );
219
- *
220
- * const child = new ChildView( locale );
221
- * this.items = this.createCollection( [ child ] );
222
- *
223
- * this.setTemplate( {
224
- * tag: 'p',
225
- *
226
- * // `items` collection will render here.
227
- * children: this.items
228
- * } );
229
- * }
230
- * }
231
- *
232
- * const view = new SampleView( locale );
233
- * view.render();
234
- *
235
- * // It will append <p><child#element></p> to the <body>.
236
- * document.body.appendChild( view.element );
237
- * ```
238
- *
239
- * @param views Initial views of the collection.
240
- * @returns A new collection of view instances.
241
- */
242
- createCollection<T extends View = View>(views?: Iterable<T>): ViewCollection<T>;
243
- /**
244
- * Registers a new child view under the view instance. Once registered, a child
245
- * view is managed by its parent, including {@link #render rendering}
246
- * and {@link #destroy destruction}.
247
- *
248
- * To revert this, use {@link #deregisterChild}.
249
- *
250
- * ```ts
251
- * class SampleView extends View {
252
- * constructor( locale ) {
253
- * super( locale );
254
- *
255
- * this.childA = new SomeChildView( locale );
256
- * this.childB = new SomeChildView( locale );
257
- *
258
- * this.setTemplate( { tag: 'p' } );
259
- *
260
- * // Register the children.
261
- * this.registerChild( [ this.childA, this.childB ] );
262
- * }
263
- *
264
- * render() {
265
- * super.render();
266
- *
267
- * this.element.appendChild( this.childA.element );
268
- * this.element.appendChild( this.childB.element );
269
- * }
270
- * }
271
- *
272
- * const view = new SampleView( locale );
273
- *
274
- * view.render();
275
- *
276
- * // Will append <p><childA#element><b></b><childB#element></p>.
277
- * document.body.appendChild( view.element );
278
- * ```
279
- *
280
- * **Note**: There's no need to add child views if they're already referenced in the
281
- * {@link #template}:
282
- *
283
- * ```ts
284
- * class SampleView extends View {
285
- * constructor( locale ) {
286
- * super( locale );
287
- *
288
- * this.childA = new SomeChildView( locale );
289
- * this.childB = new SomeChildView( locale );
290
- *
291
- * this.setTemplate( {
292
- * tag: 'p',
293
- *
294
- * // These children will be added automatically. There's no
295
- * // need to call {@link #registerChild} for any of them.
296
- * children: [ this.childA, this.childB ]
297
- * } );
298
- * }
299
- *
300
- * // ...
301
- * }
302
- * ```
303
- *
304
- * @param children Children views to be registered.
305
- */
306
- registerChild(children: View | Iterable<View>): void;
307
- /**
308
- * The opposite of {@link #registerChild}. Removes a child view from this view instance.
309
- * Once removed, the child is no longer managed by its parent, e.g. it can safely
310
- * become a child of another parent view.
311
- *
312
- * @see #registerChild
313
- * @param children Child views to be removed.
314
- */
315
- deregisterChild(children: View | Iterable<View>): void;
316
- /**
317
- * Sets the {@link #template} of the view with with given definition.
318
- *
319
- * A shorthand for:
320
- *
321
- * ```ts
322
- * view.setTemplate( definition );
323
- * ```
324
- *
325
- * @param definition Definition of view's template.
326
- */
327
- setTemplate(definition: TemplateDefinition): void;
328
- /**
329
- * {@link module:ui/template~Template.extend Extends} the {@link #template} of the view with
330
- * with given definition.
331
- *
332
- * A shorthand for:
333
- *
334
- * ```ts
335
- * Template.extend( view.template, definition );
336
- * ```
337
- *
338
- * **Note**: Is requires the {@link #template} to be already set. See {@link #setTemplate}.
339
- *
340
- * @param definition Definition which extends the {@link #template}.
341
- */
342
- extendTemplate(definition: Partial<TemplateDefinition>): void;
343
- /**
344
- * Recursively renders the view.
345
- *
346
- * Once the view is rendered:
347
- * * the {@link #element} becomes an HTML element out of {@link #template},
348
- * * the {@link #isRendered} flag is set `true`.
349
- *
350
- * **Note**: The children of the view:
351
- * * defined directly in the {@link #template}
352
- * * residing in collections created by the {@link #createCollection} method,
353
- * * and added by {@link #registerChild}
354
- * are also rendered in the process.
355
- *
356
- * In general, `render()` method is the right place to keep the code which refers to the
357
- * {@link #element} and should be executed at the very beginning of the view's life cycle.
358
- *
359
- * It is possible to {@link module:ui/template~Template.extend} the {@link #template} before
360
- * the view is rendered. To allow an early customization of the view (e.g. by its parent),
361
- * such references should be done in `render()`.
362
- *
363
- * ```ts
364
- * class SampleView extends View {
365
- * constructor() {
366
- * this.setTemplate( {
367
- * // ...
368
- * } );
369
- * },
370
- *
371
- * render() {
372
- * // View#element becomes available.
373
- * super.render();
374
- *
375
- * // The "scroll" listener depends on #element.
376
- * this.listenTo( window, 'scroll', () => {
377
- * // A reference to #element would render the #template and make it non-extendable.
378
- * if ( window.scrollY > 0 ) {
379
- * this.element.scrollLeft = 100;
380
- * } else {
381
- * this.element.scrollLeft = 0;
382
- * }
383
- * } );
384
- * }
385
- * }
386
- *
387
- * const view = new SampleView();
388
- *
389
- * // Let's customize the view before it gets rendered.
390
- * view.extendTemplate( {
391
- * attributes: {
392
- * class: [
393
- * 'additional-class'
394
- * ]
395
- * }
396
- * } );
397
- *
398
- * // Late rendering allows customization of the view.
399
- * view.render();
400
- * ```
401
- */
402
- render(): void;
403
- /**
404
- * Recursively destroys the view instance and child views added by {@link #registerChild} and
405
- * residing in collections created by the {@link #createCollection}.
406
- *
407
- * Destruction disables all event listeners:
408
- * * created on the view, e.g. `view.on( 'event', () => {} )`,
409
- * * defined in the {@link #template} for DOM events.
410
- */
411
- destroy(): void;
412
- }
413
- /**
414
- * Event fired by the {@link module:ui/view~View#render} method. Actual rendering is executed as a listener to
415
- * this event with the default priority.
416
- *
417
- * See {@link module:utils/observablemixin~Observable#decorate} for more information and samples.
418
- *
419
- * @eventName ~View#render
420
- */
421
- export type UIViewRenderEvent = DecoratedMethodEvent<View, 'render'>;
422
- export {};
1
+ /**
2
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
3
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
4
+ */
5
+ /**
6
+ * @module ui/view
7
+ */
8
+ import ViewCollection from './viewcollection';
9
+ import Template, { type BindChain, type TemplateDefinition } from './template';
10
+ import { Collection, type DecoratedMethodEvent, type Locale, type LocaleTranslate } from '@ckeditor/ckeditor5-utils';
11
+ import '../theme/globals/globals.css';
12
+ declare const View_base: import("@ckeditor/ckeditor5-utils").Mixed<{
13
+ new (): import("@ckeditor/ckeditor5-utils").Observable;
14
+ prototype: import("@ckeditor/ckeditor5-utils").Observable;
15
+ }, import("@ckeditor/ckeditor5-utils").DomEmitter>;
16
+ /**
17
+ * The basic view class, which represents an HTML element created out of a
18
+ * {@link module:ui/view~View#template}. Views are building blocks of the user interface and handle
19
+ * interaction
20
+ *
21
+ * Views {@link module:ui/view~View#registerChild aggregate} children in
22
+ * {@link module:ui/view~View#createCollection collections} and manage the life cycle of DOM
23
+ * listeners e.g. by handling rendering and destruction.
24
+ *
25
+ * See the {@link module:ui/template~TemplateDefinition} syntax to learn more about shaping view
26
+ * elements, attributes and listeners.
27
+ *
28
+ * ```ts
29
+ * class SampleView extends View {
30
+ * constructor( locale ) {
31
+ * super( locale );
32
+ *
33
+ * const bind = this.bindTemplate;
34
+ *
35
+ * // Views define their interface (state) using observable attributes.
36
+ * this.set( 'elementClass', 'bar' );
37
+ *
38
+ * this.setTemplate( {
39
+ * tag: 'p',
40
+ *
41
+ * // The element of the view can be defined with its children.
42
+ * children: [
43
+ * 'Hello',
44
+ * {
45
+ * tag: 'b',
46
+ * children: [ 'world!' ]
47
+ * }
48
+ * ],
49
+ * attributes: {
50
+ * class: [
51
+ * 'foo',
52
+ *
53
+ * // Observable attributes control the state of the view in DOM.
54
+ * bind.to( 'elementClass' )
55
+ * ]
56
+ * },
57
+ * on: {
58
+ * // Views listen to DOM events and propagate them.
59
+ * click: bind.to( 'clicked' )
60
+ * }
61
+ * } );
62
+ * }
63
+ * }
64
+ *
65
+ * const view = new SampleView( locale );
66
+ *
67
+ * view.render();
68
+ *
69
+ * // Append <p class="foo bar">Hello<b>world</b></p> to the <body>
70
+ * document.body.appendChild( view.element );
71
+ *
72
+ * // Change the class attribute to <p class="foo baz">Hello<b>world</b></p>
73
+ * view.elementClass = 'baz';
74
+ *
75
+ * // Respond to the "click" event in DOM by executing a custom action.
76
+ * view.on( 'clicked', () => {
77
+ * console.log( 'The view has been clicked!' );
78
+ * } );
79
+ * ```
80
+ */
81
+ export default class View<TElement extends HTMLElement = HTMLElement> extends View_base {
82
+ /**
83
+ * An HTML element of the view. `null` until {@link #render rendered}
84
+ * from the {@link #template}.
85
+ *
86
+ * ```ts
87
+ * class SampleView extends View {
88
+ * constructor() {
89
+ * super();
90
+ *
91
+ * // A template instance the #element will be created from.
92
+ * this.setTemplate( {
93
+ * tag: 'p'
94
+ *
95
+ * // ...
96
+ * } );
97
+ * }
98
+ * }
99
+ *
100
+ * const view = new SampleView();
101
+ *
102
+ * // Renders the #template.
103
+ * view.render();
104
+ *
105
+ * // Append the HTML element of the view to <body>.
106
+ * document.body.appendChild( view.element );
107
+ * ```
108
+ *
109
+ * **Note**: The element of the view can also be assigned directly:
110
+ *
111
+ * ```ts
112
+ * view.element = document.querySelector( '#my-container' );
113
+ * ```
114
+ */
115
+ element: TElement | null;
116
+ /**
117
+ * Set `true` when the view has already been {@link module:ui/view~View#render rendered}.
118
+ *
119
+ * @readonly
120
+ */
121
+ isRendered: boolean;
122
+ /**
123
+ * A set of tools to localize the user interface.
124
+ *
125
+ * Also see {@link module:core/editor/editor~Editor#locale}.
126
+ *
127
+ * @readonly
128
+ */
129
+ locale: Locale | undefined;
130
+ /**
131
+ * Shorthand for {@link module:utils/locale~Locale#t}.
132
+ *
133
+ * Note: If {@link #locale} instance hasn't been passed to the view this method may not
134
+ * be available.
135
+ *
136
+ * @see module:utils/locale~Locale#t
137
+ */
138
+ t: LocaleTranslate | undefined;
139
+ /**
140
+ * Template of this view. It provides the {@link #element} representing
141
+ * the view in DOM, which is {@link #render rendered}.
142
+ */
143
+ template?: Template;
144
+ viewUid?: string;
145
+ /**
146
+ * Collections registered with {@link #createCollection}.
147
+ */
148
+ protected _viewCollections: Collection<ViewCollection>;
149
+ /**
150
+ * A collection of view instances, which have been added directly
151
+ * into the {@link module:ui/template~Template#children}.
152
+ */
153
+ protected _unboundChildren: ViewCollection;
154
+ /**
155
+ * Cached {@link module:ui/template~BindChain bind chain} object created by the
156
+ * {@link #template}. See {@link #bindTemplate}.
157
+ */
158
+ private _bindTemplate?;
159
+ /**
160
+ * Creates an instance of the {@link module:ui/view~View} class.
161
+ *
162
+ * Also see {@link #render}.
163
+ *
164
+ * @param locale The localization services instance.
165
+ */
166
+ constructor(locale?: Locale);
167
+ /**
168
+ * Shorthand for {@link module:ui/template~Template.bind}, a binding
169
+ * {@link module:ui/template~BindChain interface} pre–configured for the view instance.
170
+ *
171
+ * It provides {@link module:ui/template~BindChain#to `to()`} and
172
+ * {@link module:ui/template~BindChain#if `if()`} methods that initialize bindings with
173
+ * observable attributes and attach DOM listeners.
174
+ *
175
+ * ```ts
176
+ * class SampleView extends View {
177
+ * constructor( locale ) {
178
+ * super( locale );
179
+ *
180
+ * const bind = this.bindTemplate;
181
+ *
182
+ * // These {@link module:utils/observablemixin~Observable observable} attributes will control
183
+ * // the state of the view in DOM.
184
+ * this.set( {
185
+ * elementClass: 'foo',
186
+ * isEnabled: true
187
+ * } );
188
+ *
189
+ * this.setTemplate( {
190
+ * tag: 'p',
191
+ *
192
+ * attributes: {
193
+ * // The class HTML attribute will follow elementClass
194
+ * // and isEnabled view attributes.
195
+ * class: [
196
+ * bind.to( 'elementClass' )
197
+ * bind.if( 'isEnabled', 'present-when-enabled' )
198
+ * ]
199
+ * },
200
+ *
201
+ * on: {
202
+ * // The view will fire the "clicked" event upon clicking <p> in DOM.
203
+ * click: bind.to( 'clicked' )
204
+ * }
205
+ * } );
206
+ * }
207
+ * }
208
+ * ```
209
+ */
210
+ get bindTemplate(): BindChain<this>;
211
+ /**
212
+ * Creates a new collection of views, which can be used as
213
+ * {@link module:ui/template~Template#children} of this view.
214
+ *
215
+ * ```ts
216
+ * class SampleView extends View {
217
+ * constructor( locale ) {
218
+ * super( locale );
219
+ *
220
+ * const child = new ChildView( locale );
221
+ * this.items = this.createCollection( [ child ] );
222
+ *
223
+ * this.setTemplate( {
224
+ * tag: 'p',
225
+ *
226
+ * // `items` collection will render here.
227
+ * children: this.items
228
+ * } );
229
+ * }
230
+ * }
231
+ *
232
+ * const view = new SampleView( locale );
233
+ * view.render();
234
+ *
235
+ * // It will append <p><child#element></p> to the <body>.
236
+ * document.body.appendChild( view.element );
237
+ * ```
238
+ *
239
+ * @param views Initial views of the collection.
240
+ * @returns A new collection of view instances.
241
+ */
242
+ createCollection<T extends View = View>(views?: Iterable<T>): ViewCollection<T>;
243
+ /**
244
+ * Registers a new child view under the view instance. Once registered, a child
245
+ * view is managed by its parent, including {@link #render rendering}
246
+ * and {@link #destroy destruction}.
247
+ *
248
+ * To revert this, use {@link #deregisterChild}.
249
+ *
250
+ * ```ts
251
+ * class SampleView extends View {
252
+ * constructor( locale ) {
253
+ * super( locale );
254
+ *
255
+ * this.childA = new SomeChildView( locale );
256
+ * this.childB = new SomeChildView( locale );
257
+ *
258
+ * this.setTemplate( { tag: 'p' } );
259
+ *
260
+ * // Register the children.
261
+ * this.registerChild( [ this.childA, this.childB ] );
262
+ * }
263
+ *
264
+ * render() {
265
+ * super.render();
266
+ *
267
+ * this.element.appendChild( this.childA.element );
268
+ * this.element.appendChild( this.childB.element );
269
+ * }
270
+ * }
271
+ *
272
+ * const view = new SampleView( locale );
273
+ *
274
+ * view.render();
275
+ *
276
+ * // Will append <p><childA#element><b></b><childB#element></p>.
277
+ * document.body.appendChild( view.element );
278
+ * ```
279
+ *
280
+ * **Note**: There's no need to add child views if they're already referenced in the
281
+ * {@link #template}:
282
+ *
283
+ * ```ts
284
+ * class SampleView extends View {
285
+ * constructor( locale ) {
286
+ * super( locale );
287
+ *
288
+ * this.childA = new SomeChildView( locale );
289
+ * this.childB = new SomeChildView( locale );
290
+ *
291
+ * this.setTemplate( {
292
+ * tag: 'p',
293
+ *
294
+ * // These children will be added automatically. There's no
295
+ * // need to call {@link #registerChild} for any of them.
296
+ * children: [ this.childA, this.childB ]
297
+ * } );
298
+ * }
299
+ *
300
+ * // ...
301
+ * }
302
+ * ```
303
+ *
304
+ * @param children Children views to be registered.
305
+ */
306
+ registerChild(children: View | Iterable<View>): void;
307
+ /**
308
+ * The opposite of {@link #registerChild}. Removes a child view from this view instance.
309
+ * Once removed, the child is no longer managed by its parent, e.g. it can safely
310
+ * become a child of another parent view.
311
+ *
312
+ * @see #registerChild
313
+ * @param children Child views to be removed.
314
+ */
315
+ deregisterChild(children: View | Iterable<View>): void;
316
+ /**
317
+ * Sets the {@link #template} of the view with with given definition.
318
+ *
319
+ * A shorthand for:
320
+ *
321
+ * ```ts
322
+ * view.setTemplate( definition );
323
+ * ```
324
+ *
325
+ * @param definition Definition of view's template.
326
+ */
327
+ setTemplate(definition: TemplateDefinition): void;
328
+ /**
329
+ * {@link module:ui/template~Template.extend Extends} the {@link #template} of the view with
330
+ * with given definition.
331
+ *
332
+ * A shorthand for:
333
+ *
334
+ * ```ts
335
+ * Template.extend( view.template, definition );
336
+ * ```
337
+ *
338
+ * **Note**: Is requires the {@link #template} to be already set. See {@link #setTemplate}.
339
+ *
340
+ * @param definition Definition which extends the {@link #template}.
341
+ */
342
+ extendTemplate(definition: Partial<TemplateDefinition>): void;
343
+ /**
344
+ * Recursively renders the view.
345
+ *
346
+ * Once the view is rendered:
347
+ * * the {@link #element} becomes an HTML element out of {@link #template},
348
+ * * the {@link #isRendered} flag is set `true`.
349
+ *
350
+ * **Note**: The children of the view:
351
+ * * defined directly in the {@link #template}
352
+ * * residing in collections created by the {@link #createCollection} method,
353
+ * * and added by {@link #registerChild}
354
+ * are also rendered in the process.
355
+ *
356
+ * In general, `render()` method is the right place to keep the code which refers to the
357
+ * {@link #element} and should be executed at the very beginning of the view's life cycle.
358
+ *
359
+ * It is possible to {@link module:ui/template~Template.extend} the {@link #template} before
360
+ * the view is rendered. To allow an early customization of the view (e.g. by its parent),
361
+ * such references should be done in `render()`.
362
+ *
363
+ * ```ts
364
+ * class SampleView extends View {
365
+ * constructor() {
366
+ * this.setTemplate( {
367
+ * // ...
368
+ * } );
369
+ * },
370
+ *
371
+ * render() {
372
+ * // View#element becomes available.
373
+ * super.render();
374
+ *
375
+ * // The "scroll" listener depends on #element.
376
+ * this.listenTo( window, 'scroll', () => {
377
+ * // A reference to #element would render the #template and make it non-extendable.
378
+ * if ( window.scrollY > 0 ) {
379
+ * this.element.scrollLeft = 100;
380
+ * } else {
381
+ * this.element.scrollLeft = 0;
382
+ * }
383
+ * } );
384
+ * }
385
+ * }
386
+ *
387
+ * const view = new SampleView();
388
+ *
389
+ * // Let's customize the view before it gets rendered.
390
+ * view.extendTemplate( {
391
+ * attributes: {
392
+ * class: [
393
+ * 'additional-class'
394
+ * ]
395
+ * }
396
+ * } );
397
+ *
398
+ * // Late rendering allows customization of the view.
399
+ * view.render();
400
+ * ```
401
+ */
402
+ render(): void;
403
+ /**
404
+ * Recursively destroys the view instance and child views added by {@link #registerChild} and
405
+ * residing in collections created by the {@link #createCollection}.
406
+ *
407
+ * Destruction disables all event listeners:
408
+ * * created on the view, e.g. `view.on( 'event', () => {} )`,
409
+ * * defined in the {@link #template} for DOM events.
410
+ */
411
+ destroy(): void;
412
+ }
413
+ /**
414
+ * Event fired by the {@link module:ui/view~View#render} method. Actual rendering is executed as a listener to
415
+ * this event with the default priority.
416
+ *
417
+ * See {@link module:utils/observablemixin~Observable#decorate} for more information and samples.
418
+ *
419
+ * @eventName ~View#render
420
+ */
421
+ export type UIViewRenderEvent = DecoratedMethodEvent<View, 'render'>;
422
+ export {};