@ckeditor/ckeditor5-ai 49.0.1 → 49.1.0-alpha.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 (208) hide show
  1. package/dist/aiactions/aiactions.d.ts +2 -2
  2. package/dist/aiballoon/ui/aiballoonview.d.ts +1 -1
  3. package/dist/aichat/aichatballoon.d.ts +1 -1
  4. package/dist/aichat/aichatcontroller.d.ts +2 -2
  5. package/dist/aichat/ui/aichatfeedview.d.ts +24 -0
  6. package/dist/aichat/ui/feed/aichatfeedsuggestionitemactionsview.d.ts +7 -0
  7. package/dist/aichatshortcuts/aichatshortcuts.d.ts +2 -2
  8. package/dist/aicore/aiconnector.d.ts +2 -2
  9. package/dist/aicore/aiediting.d.ts +8 -4
  10. package/dist/aicore/aieditorconfig.d.ts +225 -0
  11. package/dist/aicore/aigateway.d.ts +8 -3
  12. package/dist/aicore/model/aicontext.d.ts +2 -2
  13. package/dist/aicore/pipeline/airesponseapplier.d.ts +1 -0
  14. package/dist/aicore/ui/aiscrollfillerview.d.ts +37 -0
  15. package/dist/aicore/ui/suggestioncontainer/aisuggestionbodyview.d.ts +6 -1
  16. package/dist/aicore/ui/suggestioncontainer/aisuggestioncontentpartstateview.d.ts +7 -0
  17. package/dist/aicore/utils/autoadvancedelay.d.ts +13 -0
  18. package/dist/aicore/utils/getallowedcustomelements.d.ts +16 -0
  19. package/dist/aicore/utils/geteditorconfig.d.ts +10 -76
  20. package/dist/aicore/utils/getoperationsfordocumentsuggestions.d.ts +4 -4
  21. package/dist/aicore/utils/getrootinfo.d.ts +2 -19
  22. package/dist/aicore/utils/getscrolltoptoelement.d.ts +13 -0
  23. package/dist/aicore/utils/getsuggestionpartsfromreply.d.ts +35 -0
  24. package/dist/aicore/utils/htmlparser.d.ts +3 -2
  25. package/dist/aicore/utils/replyactions.d.ts +10 -2
  26. package/dist/aicore/utils/scrollmanager.d.ts +5 -0
  27. package/dist/aireviewcore/aireviewcoreediting.d.ts +2 -2
  28. package/dist/aireviewcore/aireviewcoreui.d.ts +8 -0
  29. package/dist/aireviewcore/model/aireviewcheckrun.d.ts +8 -0
  30. package/dist/aireviewcore/ui/aireviewcorenavigationpanelview.d.ts +1 -1
  31. package/dist/aireviewcore/ui/aireviewcoreuicheckresultsview.d.ts +22 -7
  32. package/dist/aireviewmode/aireviewmodecontroller.d.ts +4 -0
  33. package/dist/aireviewmode/ui/aireviewmodecheckresultsview.d.ts +10 -1
  34. package/dist/aireviewmode/ui/aireviewmodesummaryview.d.ts +44 -0
  35. package/dist/augmentation.d.ts +6 -0
  36. package/dist/index-editor.css +328 -166
  37. package/dist/index.css +328 -166
  38. package/dist/index.d.ts +10 -4
  39. package/dist/index.js +21 -19
  40. package/dist/toolkit/applypatch.d.ts +31 -0
  41. package/dist/toolkit/computechanges.d.ts +19 -0
  42. package/dist/toolkit/computepreviews.d.ts +39 -0
  43. package/dist/toolkit/createfragmentfromrange.d.ts +24 -0
  44. package/dist/toolkit/dataidassigner.d.ts +38 -0
  45. package/dist/toolkit/documentcompare.d.ts +357 -0
  46. package/dist/{aisdk → toolkit}/documentcompareutils.d.ts +1 -1
  47. package/dist/{aisdk/documentchanges.d.ts → toolkit/documentdiffer.d.ts} +39 -21
  48. package/dist/toolkit/documentdifferutils.d.ts +15 -0
  49. package/dist/{aisdk → toolkit}/documentsnapshot.d.ts +9 -4
  50. package/dist/toolkit/elementcategory.d.ts +50 -0
  51. package/dist/toolkit/elementmatcher.d.ts +114 -0
  52. package/dist/{aisdk → toolkit}/extractselectionfromhtml.d.ts +1 -1
  53. package/dist/toolkit/proposedchange.d.ts +113 -0
  54. package/dist/toolkit/proposedchanges.d.ts +130 -0
  55. package/dist/toolkit/proposedchangescollection.d.ts +93 -0
  56. package/dist/toolkit/proposedchangescontroller.d.ts +129 -0
  57. package/dist/toolkit/proposedchangescontrollertype.d.ts +88 -0
  58. package/dist/{aisdk/documentchangesutils.d.ts → toolkit/proposedchangesutils.d.ts} +3 -3
  59. package/dist/{aisdk → toolkit}/validateoperations.d.ts +1 -1
  60. package/dist/translations/af.js +1 -1
  61. package/dist/translations/af.umd.js +1 -1
  62. package/dist/translations/ar.js +1 -1
  63. package/dist/translations/ar.umd.js +1 -1
  64. package/dist/translations/ast.js +1 -1
  65. package/dist/translations/ast.umd.js +1 -1
  66. package/dist/translations/az.js +1 -1
  67. package/dist/translations/az.umd.js +1 -1
  68. package/dist/translations/be.js +1 -1
  69. package/dist/translations/be.umd.js +1 -1
  70. package/dist/translations/bg.js +1 -1
  71. package/dist/translations/bg.umd.js +1 -1
  72. package/dist/translations/bn.js +1 -1
  73. package/dist/translations/bn.umd.js +1 -1
  74. package/dist/translations/bs.js +1 -1
  75. package/dist/translations/bs.umd.js +1 -1
  76. package/dist/translations/ca.js +1 -1
  77. package/dist/translations/ca.umd.js +1 -1
  78. package/dist/translations/cs.js +1 -1
  79. package/dist/translations/cs.umd.js +1 -1
  80. package/dist/translations/da.js +1 -1
  81. package/dist/translations/da.umd.js +1 -1
  82. package/dist/translations/de-ch.js +1 -1
  83. package/dist/translations/de-ch.umd.js +1 -1
  84. package/dist/translations/de.js +1 -1
  85. package/dist/translations/de.umd.js +1 -1
  86. package/dist/translations/el.js +1 -1
  87. package/dist/translations/el.umd.js +1 -1
  88. package/dist/translations/en-au.js +1 -1
  89. package/dist/translations/en-au.umd.js +1 -1
  90. package/dist/translations/en-gb.js +1 -1
  91. package/dist/translations/en-gb.umd.js +1 -1
  92. package/dist/translations/en.js +1 -1
  93. package/dist/translations/en.umd.js +1 -1
  94. package/dist/translations/eo.js +1 -1
  95. package/dist/translations/eo.umd.js +1 -1
  96. package/dist/translations/es-co.js +1 -1
  97. package/dist/translations/es-co.umd.js +1 -1
  98. package/dist/translations/es.js +1 -1
  99. package/dist/translations/es.umd.js +1 -1
  100. package/dist/translations/et.js +1 -1
  101. package/dist/translations/et.umd.js +1 -1
  102. package/dist/translations/eu.js +1 -1
  103. package/dist/translations/eu.umd.js +1 -1
  104. package/dist/translations/fa.js +1 -1
  105. package/dist/translations/fa.umd.js +1 -1
  106. package/dist/translations/fi.js +1 -1
  107. package/dist/translations/fi.umd.js +1 -1
  108. package/dist/translations/fr.js +1 -1
  109. package/dist/translations/fr.umd.js +1 -1
  110. package/dist/translations/gl.js +1 -1
  111. package/dist/translations/gl.umd.js +1 -1
  112. package/dist/translations/gu.js +1 -1
  113. package/dist/translations/gu.umd.js +1 -1
  114. package/dist/translations/he.js +1 -1
  115. package/dist/translations/he.umd.js +1 -1
  116. package/dist/translations/hi.js +1 -1
  117. package/dist/translations/hi.umd.js +1 -1
  118. package/dist/translations/hr.js +1 -1
  119. package/dist/translations/hr.umd.js +1 -1
  120. package/dist/translations/hu.js +1 -1
  121. package/dist/translations/hu.umd.js +1 -1
  122. package/dist/translations/hy.js +1 -1
  123. package/dist/translations/hy.umd.js +1 -1
  124. package/dist/translations/id.js +1 -1
  125. package/dist/translations/id.umd.js +1 -1
  126. package/dist/translations/it.js +1 -1
  127. package/dist/translations/it.umd.js +1 -1
  128. package/dist/translations/ja.js +1 -1
  129. package/dist/translations/ja.umd.js +1 -1
  130. package/dist/translations/jv.js +1 -1
  131. package/dist/translations/jv.umd.js +1 -1
  132. package/dist/translations/kk.js +1 -1
  133. package/dist/translations/kk.umd.js +1 -1
  134. package/dist/translations/km.js +1 -1
  135. package/dist/translations/km.umd.js +1 -1
  136. package/dist/translations/kn.js +1 -1
  137. package/dist/translations/kn.umd.js +1 -1
  138. package/dist/translations/ko.js +1 -1
  139. package/dist/translations/ko.umd.js +1 -1
  140. package/dist/translations/ku.js +1 -1
  141. package/dist/translations/ku.umd.js +1 -1
  142. package/dist/translations/lt.js +1 -1
  143. package/dist/translations/lt.umd.js +1 -1
  144. package/dist/translations/lv.js +1 -1
  145. package/dist/translations/lv.umd.js +1 -1
  146. package/dist/translations/ms.js +1 -1
  147. package/dist/translations/ms.umd.js +1 -1
  148. package/dist/translations/nb.js +1 -1
  149. package/dist/translations/nb.umd.js +1 -1
  150. package/dist/translations/ne.js +1 -1
  151. package/dist/translations/ne.umd.js +1 -1
  152. package/dist/translations/nl.js +1 -1
  153. package/dist/translations/nl.umd.js +1 -1
  154. package/dist/translations/no.js +1 -1
  155. package/dist/translations/no.umd.js +1 -1
  156. package/dist/translations/oc.js +1 -1
  157. package/dist/translations/oc.umd.js +1 -1
  158. package/dist/translations/pl.js +1 -1
  159. package/dist/translations/pl.umd.js +1 -1
  160. package/dist/translations/pt-br.js +1 -1
  161. package/dist/translations/pt-br.umd.js +1 -1
  162. package/dist/translations/pt.js +1 -1
  163. package/dist/translations/pt.umd.js +1 -1
  164. package/dist/translations/ro.js +1 -1
  165. package/dist/translations/ro.umd.js +1 -1
  166. package/dist/translations/ru.js +1 -1
  167. package/dist/translations/ru.umd.js +1 -1
  168. package/dist/translations/si.js +1 -1
  169. package/dist/translations/si.umd.js +1 -1
  170. package/dist/translations/sk.js +1 -1
  171. package/dist/translations/sk.umd.js +1 -1
  172. package/dist/translations/sl.js +1 -1
  173. package/dist/translations/sl.umd.js +1 -1
  174. package/dist/translations/sq.js +1 -1
  175. package/dist/translations/sq.umd.js +1 -1
  176. package/dist/translations/sr-latn.js +1 -1
  177. package/dist/translations/sr-latn.umd.js +1 -1
  178. package/dist/translations/sr.js +1 -1
  179. package/dist/translations/sr.umd.js +1 -1
  180. package/dist/translations/sv.js +1 -1
  181. package/dist/translations/sv.umd.js +1 -1
  182. package/dist/translations/th.js +1 -1
  183. package/dist/translations/th.umd.js +1 -1
  184. package/dist/translations/ti.js +1 -1
  185. package/dist/translations/ti.umd.js +1 -1
  186. package/dist/translations/tk.js +1 -1
  187. package/dist/translations/tk.umd.js +1 -1
  188. package/dist/translations/tr.js +1 -1
  189. package/dist/translations/tr.umd.js +1 -1
  190. package/dist/translations/tt.js +1 -1
  191. package/dist/translations/tt.umd.js +1 -1
  192. package/dist/translations/ug.js +1 -1
  193. package/dist/translations/ug.umd.js +1 -1
  194. package/dist/translations/uk.js +1 -1
  195. package/dist/translations/uk.umd.js +1 -1
  196. package/dist/translations/ur.js +1 -1
  197. package/dist/translations/ur.umd.js +1 -1
  198. package/dist/translations/uz.js +1 -1
  199. package/dist/translations/uz.umd.js +1 -1
  200. package/dist/translations/vi.js +1 -1
  201. package/dist/translations/vi.umd.js +1 -1
  202. package/dist/translations/zh-cn.js +1 -1
  203. package/dist/translations/zh-cn.umd.js +1 -1
  204. package/dist/translations/zh.js +1 -1
  205. package/dist/translations/zh.umd.js +1 -1
  206. package/package.json +32 -30
  207. package/dist/aisdk/dataidassigner.d.ts +0 -20
  208. package/dist/aisdk/documentcompare.d.ts +0 -171
@@ -3,10 +3,10 @@
3
3
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
4
  */
5
5
  /**
6
- * @module ai/aisdk/documentsnapshot
6
+ * @module ai/toolkit/documentsnapshot
7
7
  * @publicApi
8
8
  */
9
- import { type AIEditorConfig } from "../aicore/utils/geteditorconfig.js";
9
+ import { type AIEditorConfigSnapshot } from "../aicore/aieditorconfig.js";
10
10
  /**
11
11
  * A captured selection range as character offsets into its root's serialized HTML.
12
12
  */
@@ -17,7 +17,7 @@ export interface DocumentCompareSnapshotRange {
17
17
  /**
18
18
  * The captured before-state of a document plus the metadata to reconcile changes later.
19
19
  * The snapshot is a plain object and is safe to `JSON.stringify`, send between the frontend and backend, store, parse,
20
- * and later feed back into `DocumentCompare#diffSnapshot`.
20
+ * and later feed back into `DocumentCompare#computePatch`.
21
21
  */
22
22
  export interface DocumentCompareSnapshot {
23
23
  /**
@@ -33,6 +33,11 @@ export interface DocumentCompareSnapshot {
33
33
  */
34
34
  version: number;
35
35
  /**
36
+ * Whether the snapshot document data is stamped with `data-id` attributes. If yes, `data-id`s are used to pair elements.
37
+ * If no, the elements are paired by their content instead.
38
+ */
39
+ useDataIds: boolean;
40
+ /**
36
41
  * Each root's content, serialized to HTML, keyed by root name (excluding `$graveyard`).
37
42
  */
38
43
  content: Record<string, string>;
@@ -44,5 +49,5 @@ export interface DocumentCompareSnapshot {
44
49
  * The editor's feature configuration at capture time, so external processing can interpret the serialized HTML
45
50
  * within the editor's capabilities.
46
51
  */
47
- editorConfig: AIEditorConfig;
52
+ editorConfig: AIEditorConfigSnapshot;
48
53
  }
@@ -0,0 +1,50 @@
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
+ */
5
+ /**
6
+ * @module ai/toolkit/elementcategory
7
+ */
8
+ import { type ModelElement, type ModelSchema } from "@ckeditor/ckeditor5-engine";
9
+ /**
10
+ * Name of the model attribute which carries the element id used by the document comparison.
11
+ *
12
+ * It is a temporary attribute that exists only on content processed by `DocumentDiffer`, never in the document data.
13
+ */
14
+ export declare const DATA_ID_MODEL_ATTRIBUTE = "$elementId";
15
+ /**
16
+ * Name of the view (HTML) attribute which is upcast to {@link ~DATA_ID_MODEL_ATTRIBUTE}.
17
+ */
18
+ export declare const DATA_ID_VIEW_ATTRIBUTE = "data-id";
19
+ /**
20
+ * Describes how an element behaves in a document comparison and how it can change.
21
+ *
22
+ * * `block` - elements like paragraphs, lists, or headings. Can be renamed. Can be created by splitting. Can be removed by merging.
23
+ * Its contents can be "moved around" by splitting or merging.
24
+ *
25
+ * * `container` - elements like blockquote. Cannot be renamed. Can be created by wrapping. Can be removed by unwrapping. Can be
26
+ * "resized" by having other elements be moved into or out of them.
27
+ *
28
+ * * `solid` - limit-like elements like table or image. Cannot be renamed, split or merged. Can be added by insertion and removed by
29
+ * deletion. If added or removed, all their content also should be treated as added or removed.
30
+ */
31
+ export type ModelElementCategory = "block" | "container" | "solid";
32
+ /**
33
+ * Returns the {@link ~ModelElementCategory category} of the element, based on the schema.
34
+ *
35
+ * The same classification drives both the diff algorithm in `DocumentDiffer` and the content-based element matching, so
36
+ * the two never disagree on what an element is.
37
+ */
38
+ export declare function getElementCategory(element: ModelElement, schema: ModelSchema): ModelElementCategory;
39
+ /**
40
+ * Returns `true` when the element holds a `$text` child and unwrapping into the element's parent
41
+ * would strand it - i.e. parent is a non-block element that doesn't accept text.
42
+ *
43
+ * That's the shape the diff algorithm can't compute valid operations for: an unwrap would leave
44
+ * bare text in a parent that doesn't allow it, and `DocumentDiffer` doesn't synthesise a paragraph
45
+ * wrap to make the result valid.
46
+ *
47
+ * With GHS this fires for `htmlSummary`, `htmlCaption`, `htmlFigcaption`, `htmlLegend`, `htmlLi`
48
+ * when they hold text (and the native plugin that normally handles them is not loaded).
49
+ */
50
+ export declare function isStructurallyBoundElement(element: ModelElement, schema: ModelSchema): boolean;
@@ -0,0 +1,114 @@
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
+ */
5
+ /**
6
+ * @module ai/toolkit/elementmatcher
7
+ */
8
+ import { type ModelDocumentFragment, type ModelElement, type ModelSchema } from "@ckeditor/ckeditor5-engine";
9
+ /**
10
+ * Similarity threshold from which two paired blocks (paragraphs, headings, list items) are treated as the same element.
11
+ *
12
+ * The value is low on purpose to also match "containment cases". A paragraph kept whole and grown `k` times scores `2 / ( 1 + k )`,
13
+ * so `0.3` keeps the identity of a paragraph grown up to about five times. At the same time, `0.3` means pairing two texts that share about
14
+ * a third of their characters in words.
15
+ *
16
+ * Widgets (limit elements) have no such bar. A table kept in the same place is considered the same table, changed inside.
17
+ */
18
+ export declare const PAIR_THRESHOLD = .3;
19
+ /**
20
+ * Fixed value by which every similarity rate is decreased.
21
+ *
22
+ * It skews the alignment towards identical and almost identical pairs. An identical pair (`similarity = 1.0`) counts as `0.7`, while a
23
+ * pair at `similarity = 0.5` counts as `0.2`. When elements are matched, one strong pair wins over many weak ones.
24
+ *
25
+ * It must not exceed {@link ~PAIR_THRESHOLD}.
26
+ */
27
+ export declare const PAIR_COST: number;
28
+ /**
29
+ * A very minimal score, attributed to any pair of elements that can be compared.
30
+ *
31
+ * The reason for this is to prefer making any pair than not having a pair at all. Two comparable elements standing at same positions are
32
+ * scored with `MIN_PAIR_WEIGHT` rather than `0`, and will be paired if there are no better candidates.
33
+ */
34
+ export declare const MIN_PAIR_WEIGHT = .001;
35
+ /**
36
+ * Penalty per position off the diagonal in the alignment objective.
37
+ *
38
+ * This is to decide tie-breaks between pairs that score the same. When multiple pairs with same score are considered, we prefer elements
39
+ * that are closer to each other.
40
+ */
41
+ export declare const POSITION_PENALTY = 1e-9;
42
+ /**
43
+ * Band size describes how many elements we compare, so that we don't compare all elements with each other.
44
+ *
45
+ * For an element from "before" document, which is at position `i`, we compare it with all "after elements" at positions from
46
+ * `i - band_size` to `i + band_size`.
47
+ *
48
+ * The band size can be dynamically enlarged during the matching algorithm.
49
+ *
50
+ * `BAND_START` only describes the *base* starting value. The actual band size is additionally increased by the difference between
51
+ * the length of before elements and after elements lists. This is to make sure that the band "catches" all insertions/deletions.
52
+ */
53
+ export declare const BAND_START = 8;
54
+ /**
55
+ * Maximum base band width.
56
+ *
57
+ * This is not the maximum band width, as band width is always increased by the difference between the length of before elements and
58
+ * after elements lists. So, the band starts at `BAND_START + difference` and can be at most `BAND_MAX + difference`.
59
+ */
60
+ export declare const BAND_MAX = 512;
61
+ /**
62
+ * Weight of an element that holds no words (e.g. an inline image, a merge field). Such element is "as important" as a word with
63
+ * `ELEMENT_TOKEN_WEIGHT` characters. (Small words are less important for the similarity measure than big words.)
64
+ */
65
+ export declare const ELEMENT_TOKEN_WEIGHT = 8;
66
+ /**
67
+ * Model attributes ignored by the algorithm. These are attributes with random or meaningless values, generated by the editor when the
68
+ * document data is read.
69
+ */
70
+ export declare const IGNORED_ATTRIBUTES: ReadonlySet<string>;
71
+ /**
72
+ * Model elements ignored by the algorithm.
73
+ */
74
+ export declare const IGNORED_ELEMENTS: ReadonlySet<string>;
75
+ /**
76
+ * Attributes that decide element identity.
77
+ *
78
+ * Two elements whose identity attributes agree are always treated as the same element. Two elements that differ on identity attribute
79
+ * are always treated as different elements.
80
+ *
81
+ * For example, an image is identified by what it shows (`src`), a media embed by what it points to (`url`), a merge field by its `id`, etc.
82
+ * These attributes unambiguously decide what the element "is", so the identity attribute is treated as the content.
83
+ */
84
+ export declare const DEFAULT_IDENTITY_ATTRIBUTES: Record<string, Array<string>>;
85
+ /**
86
+ * Splits text into words: anything that is not a letter or a digit separates words.
87
+ */
88
+ export declare const WORD_SEPARATOR: RegExp;
89
+ /**
90
+ * Options for {@link ~ElementMatcher}.
91
+ */
92
+ export interface ElementMatcherOptions {
93
+ /**
94
+ * Additional attributes that decide identity, by element name. An entry may be a dotted path into an object value.
95
+ */
96
+ identityAttributes?: Record<string, Array<string>>;
97
+ }
98
+ /**
99
+ * Builds a comparison of two document fragments. Create an instance per comparison and call {@link #match}.
100
+ *
101
+ * Two model document fragments -- "before" and "after" states -- are compared by their content similarity. As a result, elements that
102
+ * are decided to be the same elements on both sides (however, possibly modified) receive the same ID, while all elements that are marked
103
+ * as removed or added gain unique IDs, that do not pair with anything on the other side.
104
+ *
105
+ * This makes model fragments that originally did not have IDs ready to be diffed by {@link module:ai/toolkit/documentdiffer~DocumentDiffer}
106
+ * which requires the IDs to be set on both sides.
107
+ */
108
+ export declare class ElementMatcher {
109
+ constructor(schema: ModelSchema, options?: ElementMatcherOptions);
110
+ /**
111
+ * Pairs the elements of the two fragments and returns the ID every element should carry.
112
+ */
113
+ match(before: ModelDocumentFragment, after: ModelDocumentFragment): Map<ModelElement, string>;
114
+ }
@@ -3,7 +3,7 @@
3
3
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
4
  */
5
5
  /**
6
- * @module ai/aisdk/extractselectionfromhtml
6
+ * @module ai/toolkit/extractselectionfromhtml
7
7
  */
8
8
  import { type DocumentCompareSnapshotRange } from "./documentsnapshot.js";
9
9
  /**
@@ -0,0 +1,113 @@
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
+ */
5
+ /**
6
+ * @module ai/toolkit/proposedchange
7
+ * @publicApi
8
+ */
9
+ import { type ModelRange } from "@ckeditor/ckeditor5-engine";
10
+ import { type AIOperationSource } from "../aicore/utils/markoperationsasai.js";
11
+ /**
12
+ * Represents a single change document change.
13
+ */
14
+ export interface DocumentChange {
15
+ /**
16
+ * The name of the editor root the change applies to.
17
+ */
18
+ rootName: string;
19
+ /**
20
+ * What the change covers, represented as a range inside the captured snapshot. The range covers the existing elements which were
21
+ * either removed or modified.
22
+ *
23
+ * Note, that the range is placed inside the snapshot represented as a model document fragment, not in the actual model document. One
24
+ * snapshot model fragment is shared between all document changes in a given set.
25
+ *
26
+ * Collapsed for a change that only adds content.
27
+ */
28
+ beforeRange: ModelRange;
29
+ /**
30
+ * What the covered content becomes, represented as a range inside the processed data. The range covers existing elements which were
31
+ * modified or new elements.
32
+ *
33
+ * In other words, the document change says that `beforeRange` content becomes `afterRange` content.
34
+ *
35
+ * Note, that the range is placed inside the processed data represented as a model document fragment, not in the actual model document.
36
+ * One processed data model fragment is shared between all document changes in a given set.
37
+ *
38
+ * Collapsed for a change that only removes content.
39
+ */
40
+ afterRange: ModelRange;
41
+ /**
42
+ * The document {@link module:engine/model/document~ModelDocument#version version} for which the change is proposed.
43
+ */
44
+ version: number;
45
+ /**
46
+ * The editing session ID during which the change was captured.
47
+ */
48
+ sessionId: string;
49
+ /**
50
+ * The ID of the document the change was captured from.
51
+ */
52
+ channelId: string;
53
+ /**
54
+ * Which AI feature produced the change or not set if the change did not come from AI.
55
+ *
56
+ * See {@link module:ai/toolkit/documentcompare~DocumentCompareComputeChangesOptions#aiSource}.
57
+ */
58
+ aiSource?: AIOperationSource;
59
+ }
60
+ /**
61
+ * Holds information whether the user has interacted with the proposed document change:
62
+ *
63
+ * * `'pending'` - waiting for the user's decision.
64
+ * * `'accepted'` - applied to the document (directly or as a tracked suggestion).
65
+ * * `'rejected'` - dismissed by the user.
66
+ *
67
+ * Whether the document can still have the change applied is a separate question, see {@link ~ProposedChange#outdatedState}.
68
+ */
69
+ export type ProposedChangeState = "pending" | "accepted" | "rejected";
70
+ /**
71
+ * Holds a reason why the proposed change cannot be applied to the current state of the document.
72
+ *
73
+ * * `'content-removed'` - the related content or parent root were removed from the document.
74
+ * * `'editor-removed'` - the target editor (identified through `channelId`) is not available.
75
+ * * `'session-changed'` - the change was captured for document during a previous editing session.
76
+ */
77
+ export type ProposedChangeOutdatedState = "content-removed" | "editor-removed" | "session-changed";
78
+ /**
79
+ * Holds a reason why the proposed change yields nothing (no preview to show, and nothing an apply would do):
80
+ *
81
+ * * `'diff-empty'` - the change's two sides were compared, and nothing differs.
82
+ * * `'diff-failed'` - comparing the two sides threw, the proposed change cannot be further handled.
83
+ */
84
+ export type ProposedChangeEmptyReason = "diff-empty" | "diff-failed";
85
+ /**
86
+ * Represents a single, reviewable proposed document change. Holds both the information about the change and its current status.
87
+ */
88
+ export interface ProposedChange extends DocumentChange {
89
+ /**
90
+ * The change's position in the {@link module:ai/toolkit/proposedchangescollection~ProposedChangesCollection set}.
91
+ *
92
+ * Assigned when the set of changes is built, does not change later on.
93
+ */
94
+ index: number;
95
+ /**
96
+ * Holds information whether the user has interacted with the proposed document change.
97
+ */
98
+ state: ProposedChangeState;
99
+ /**
100
+ * If set, holds a reason why the proposed change cannot be applied to the current state of the document.
101
+ *
102
+ * If not set, the change is not outdated and can be applied to the document.
103
+ */
104
+ outdatedState?: ProposedChangeOutdatedState;
105
+ /**
106
+ * If set, holds a reason why the proposed change yields nothing (no preview to show, and nothing an apply would do).
107
+ */
108
+ emptyReason?: ProposedChangeEmptyReason;
109
+ /**
110
+ * If `true`, the change relates to content that is current in read-only mode and thus the change cannot be applied.
111
+ */
112
+ isReadOnly?: boolean;
113
+ }
@@ -0,0 +1,130 @@
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
+ */
5
+ /**
6
+ * @module ai/toolkit/proposedchanges
7
+ * @publicApi
8
+ */
9
+ import { ContextPlugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
10
+ import { type ProposedChangesController, type ProposedChangesControllerOptions } from "./proposedchangescontrollertype.js";
11
+ import { type ProposedChangesCollection } from "./proposedchangescollection.js";
12
+ import { DocumentDiffer } from "./documentdiffer.js";
13
+ import { ProposedChangesUtils } from "./proposedchangesutils.js";
14
+ import { AIEditing } from "../aicore/aiediting.js";
15
+ import { AISuggestionContainerView } from "../aicore/ui/suggestioncontainer/aisuggestioncontainerview.js";
16
+ import { type AISuggestionActionName } from "../aicore/utils/replyactions.js";
17
+ /**
18
+ * Provides both an API and a UI component for reviewing a set of
19
+ * {@link module:ai/toolkit/proposedchange~DocumentChange proposed document changes}.
20
+ *
21
+ * Use {@link #createController `createController()`} to create a
22
+ * {@link module:ai/toolkit/proposedchangescontrollertype~ProposedChangesController controller} instance which binds the proposed
23
+ * document changes with related editors.
24
+ *
25
+ * Then use {@link #createView `createView()`} to create a UI component for the proposed changes.
26
+ *
27
+ * {@link module:ai/toolkit/documentcompare~DocumentCompare#computeChanges Compute changes}, collect them into
28
+ * a {@link module:ai/toolkit/proposedchangescollection~ProposedChangesCollection set of proposed changes}, and create a controller:
29
+ *
30
+ * ```ts
31
+ * const changes = editor.plugins.get( 'DocumentCompare' ).computeChanges( snapshot, processedData );
32
+ * const collection = new ProposedChangesCollection( changes );
33
+ *
34
+ * const proposedChanges = editor.plugins.get( 'ProposedChanges' ); // Use `Context` instance if you have multiple editors.
35
+ * const controller = proposedChanges.createController( collection );
36
+ * ```
37
+ *
38
+ * To restore a review, pass each change's `state` to the set:
39
+ *
40
+ * ```ts
41
+ * const collection = new ProposedChangesCollection(
42
+ * changes.map( ( change, index ) => ( { ...change, state: savedStates[ index ] } ) )
43
+ * );
44
+ * ```
45
+ *
46
+ * {@link module:ai/toolkit/proposedchangescontrollertype~ProposedChangesController#attachView Attach} the proposed changes UI component
47
+ * and append it where you like:
48
+ *
49
+ * ```ts
50
+ * const view = proposedChanges.createView();
51
+ * controller.attachView( view );
52
+ *
53
+ * myDomContainer.appendChild( view.element );
54
+ *
55
+ * // ...
56
+ * // After the controller and view are not needed anymore, remember to destroy them:
57
+ * view.destroy();
58
+ * controller.destroy();
59
+ * ```
60
+ */
61
+ export declare class ProposedChanges extends ContextPlugin {
62
+ /**
63
+ * @inheritDoc
64
+ */
65
+ static get requires(): PluginDependenciesOf<[AIEditing, DocumentDiffer, ProposedChangesUtils]>;
66
+ /**
67
+ * @inheritDoc
68
+ */
69
+ static get pluginName(): "ProposedChanges";
70
+ /**
71
+ * @inheritDoc
72
+ */
73
+ static override get isOfficialPlugin(): true;
74
+ /**
75
+ * @inheritDoc
76
+ */
77
+ static override get isPremiumPlugin(): true;
78
+ init(): Promise<void>;
79
+ /**
80
+ * Returns a {@link module:ai/toolkit/proposedchangescontrollertype~ProposedChangesController controller} that provides all logic
81
+ * and API necessary for implementing a capability to review a set of proposed changes.
82
+ *
83
+ * {@link module:ai/toolkit/proposedchangescontrollertype~ProposedChangesController#attachView Attach} a {@link #createView view}
84
+ * to it to let the user review the changes.
85
+ *
86
+ * The controller works over the given `collection`, available afterwards as its
87
+ * {@link module:ai/toolkit/proposedchangescontrollertype~ProposedChangesController#collection}. The set is owned by the caller
88
+ * and outlives the controller, so it can be passed to a new controller, for example to continue the review after the editor was
89
+ * re-created. Destroy the controller previously bound with the set first.
90
+ *
91
+ * See the examples in the {@link module:ai/toolkit/proposedchanges~ProposedChanges `ProposedChanges` plugin documentation}
92
+ * to learn more.
93
+ *
94
+ * @param collection The set of proposed changes to review.
95
+ * @param options The controller options.
96
+ */
97
+ createController(collection: ProposedChangesCollection, options?: ProposedChangesControllerOptions): ProposedChangesController;
98
+ /**
99
+ * Returns a new view to review proposed changes. Includes a single card for each change, with the actions to accept or reject it.
100
+ * All changes are wrapped into a container with additional actions: toggle view mode, accept all changes and suggest all changes.
101
+ *
102
+ * Attach it to a {@link #createController controller} with
103
+ * {@link module:ai/toolkit/proposedchangescontrollertype~ProposedChangesController#attachView}, and place its
104
+ * {@link module:ui/view~View#element `element`} anywhere in the page.
105
+ *
106
+ * See the examples in the {@link module:ai/toolkit/proposedchanges~ProposedChanges `ProposedChanges` plugin documentation}
107
+ * to learn more.
108
+ *
109
+ * @param options The view options.
110
+ */
111
+ createView(options?: ProposedChangesViewOptions): AISuggestionContainerView;
112
+ /**
113
+ * @inheritDoc
114
+ */
115
+ override destroy(): void;
116
+ }
117
+ /**
118
+ * The options of {@link module:ai/toolkit/proposedchanges~ProposedChanges#createView}.
119
+ */
120
+ export interface ProposedChangesViewOptions {
121
+ /**
122
+ * The actions available in the view.
123
+ *
124
+ * Defaults to {@link module:ai/aicore/utils/replyactions~AI_REPLY_ACTIONS `AI_REPLY_ACTIONS`}.
125
+ *
126
+ * Suggesting changes (`'insertSuggestion'`) is offered by an attached controller only when every editor it reviews loads
127
+ * the {@link module:track-changes/trackchanges~TrackChanges track changes} feature.
128
+ */
129
+ availableActions?: Array<AISuggestionActionName>;
130
+ }
@@ -0,0 +1,93 @@
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
+ */
5
+ /**
6
+ * @module ai/toolkit/proposedchangescollection
7
+ * @publicApi
8
+ */
9
+ import { type EmitterMixinConstructor } from "@ckeditor/ckeditor5-utils";
10
+ import { type DocumentChange, type ProposedChange, type ProposedChangeState } from "./proposedchange.js";
11
+ declare const ProposedChangesCollectionBase: EmitterMixinConstructor;
12
+ /**
13
+ * A set of proposed changes for one or multiple documents. Keeps and manages these changes' current state.
14
+ *
15
+ * The changes inside one set are logically related and can be thought as one "review". They are a result of one "processing cycle": one
16
+ * set of changes, all proposed together at once, for one or multiple documents, to be reviewed and accepted or rejected.
17
+ *
18
+ * The proposed changes are given an index and are addressed by their index in the set. A change never leaves the set, and its index does
19
+ * not change. An accepted or rejected change is still kept in the set at its original index, and can be rendered for preview purposes.
20
+ *
21
+ * Create the set from the proposed changes, then pass it to
22
+ * {@link module:ai/toolkit/proposedchanges~ProposedChanges#createController create a controller}, which binds the set with related
23
+ * editor instance(s) and optionally a view component. Read the set directly, but modify it through the controller API.
24
+ *
25
+ * The set is owned by the integrator and outlives the controller. It can be passed to a new controller, for example to keep
26
+ * the review when the controller is re-created for a new editor instance. A set must be bound with one controller at a time.
27
+ */
28
+ export declare class ProposedChangesCollection extends ProposedChangesCollectionBase {
29
+ /**
30
+ * @param changes The changes to review, in the order they should be reviewed in. A change may state its
31
+ * {@link module:ai/toolkit/proposedchange~ProposedChange#state decision}, to restore a review. Defaults to `'pending'`.
32
+ */
33
+ constructor(changes?: Array<DocumentChange & {
34
+ state?: ProposedChangeState;
35
+ }>);
36
+ /**
37
+ * Returns the proposed changes.
38
+ */
39
+ getChanges(): ReadonlyArray<ProposedChange>;
40
+ /**
41
+ * Returns the proposed change at `index`, or `undefined` when the set holds none there.
42
+ *
43
+ * @param index
44
+ */
45
+ getChange(index: number): ProposedChange | undefined;
46
+ /**
47
+ * Whether the user can make an action (accept or reject) for the change at `index`.
48
+ *
49
+ * Actionable change must be in pending state (not accepted or rejected yet), it must yield actual change, it cannot be outdated
50
+ * (the related content must not be removed), and the related document must be available.
51
+ *
52
+ * If the change affects a read-only content, it is still actionable. Such a change cannot be accepted, but it can be rejected.
53
+ *
54
+ * An actionable change that can still be accepted {@link #isWritable is writeable}.
55
+ *
56
+ * @param index
57
+ */
58
+ isActionable(index: number): boolean;
59
+ /**
60
+ * Whether the change at `index` can be accepted by the user.
61
+ *
62
+ * It must {@link #isActionable be actionable} and affect content that is not read-only.
63
+ *
64
+ * @param index
65
+ */
66
+ isWritable(index: number): boolean;
67
+ /**
68
+ * Whether there is any writable ("applicable") change in the collection.
69
+ */
70
+ hasWritableChanges(): boolean;
71
+ /**
72
+ * The position of the nearest {@link #isActionable actionable} change in the given direction, or `null` when there is none.
73
+ *
74
+ * It is cyclic: "next" from the last change is the first one. `null` is returned only once there are no actionable changes in the set.
75
+ *
76
+ * @param index The index to step away from.
77
+ * @param direction Which way to step.
78
+ */
79
+ getActionableSibling(index: number, direction: "next" | "previous"): number | null;
80
+ }
81
+ /**
82
+ * Fired whenever anything about a proposed change state changes.
83
+ *
84
+ * @eventName ~ProposedChangesCollection#changeUpdated
85
+ */
86
+ export type ProposedChangeUpdatedEvent = {
87
+ name: "changeUpdated";
88
+ args: [{
89
+ index: number;
90
+ change: ProposedChange;
91
+ }];
92
+ };
93
+ export {};