jodit 3.10.2 → 3.12.2

package/index.d.ts

@@ -1,7 +1,7 @@
 /*!
  * Jodit Editor (https://xdsoft.net/jodit/)
  * Released under MIT see LICENSE.txt in the project root for license information.
- * Copyright (c) 2013-2021 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ * Copyright (c) 2013-2022 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
  */
 
 import type { IComponent, Nullable } from './src/types';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "jodit",
-	"version": "3.10.2",
+	"version": "3.12.2",
 	"description": "Jodit is awesome and usefully wysiwyg editor with filebrowser",
 	"main": "build/jodit.min.js",
 	"types": "./types/index.d.ts",
@@ -33,8 +33,18 @@
 	},
 	"keywords": [
 		"wysiwyg",
+		"wysiwyg editor",
+		"wysiwyg html editor",
+		"rich text",
+		"rich editor",
+		"rich text editor",
+		"html",
+		"text",
 		"editor",
-		"rich",
+		"contenteditable",
+		"javascript",
+		"typescript",
+		"vanillajs",
 		"jodit"
 	],
 	"author": "Chupurnov <chupurnov@gmail.com> (https://xdsoft.net/)",
@@ -82,6 +92,7 @@
 		"merge-stream": "^2.0.0",
 		"mini-css-extract-plugin": "^2.4.3",
 		"mocha": "^9.1.3",
+		"open": "^8.4.0",
 		"postcss": "^8.3.11",
 		"postcss-css-variables": "^0.18.0",
 		"postcss-loader": "^6.2.0",
@@ -98,6 +109,7 @@
 		"ts-loader": "^9.2.6",
 		"ts-private-uglifier": "^1.0.2",
 		"tslib": "^2.3.1",
+		"typedoc": "^0.22.10",
 		"typescript": "^4.5.2",
 		"url-loader": "^4.1.1",
 		"webpack": "^5.59.1",

package/src/README.md

@@ -0,0 +1,55 @@
+The Jodit editor consists of modules and plugins. Modules make up the permanent basis of the editor's work,
+and plugins can add their own functionality [[plugin]].
+
+The editor is initialized on a DOM element. It must already exist on the page:
+
+```js
+Jodit.make('#editor');
+```
+You can also set a DOM element right away.
+
+```js
+const elm = document.querySelector('#editor');
+Jodit.make(elm);
+```
+
+The [[Jodit.make]] method returns an instance of [[Jodit]].
+
+```js
+const jodit = Jodit.make('#editor');
+console.log(jodit.isReady)
+```
+
+This is almost equivalent to
+
+```js
+const jodit = new Jodit('#editor');
+console.log(jodit.isReady)
+```
+
+> But the `make` method is preferable.
+
+All customization of the editor is done through the [[Config]]:
+
+```js
+Jodit.make('#editor', {
+	height: 300
+});
+```
+
+Jodit instance has a module [[EventEmitter]]
+
+```js
+const jodit = Jodit.make('#editor');
+jodit.events.on('keydown', (e) => {
+	console.log(e.key)
+})
+```
+
+And the [[Select]] module, which allows you to manipulate the content of the editor through HTML insertion
+
+```js
+const jodit = Jodit.make('#editor');
+jodit.s.focus()
+jodit.s.insertHTML('<p>test</p>')
+```

package/src/config.ts

@@ -1,7 +1,11 @@
 /*!
  * Jodit Editor (https://xdsoft.net/jodit/)
  * Released under MIT see LICENSE.txt in the project root for license information.
- * Copyright (c) 2013-2021 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ * Copyright (c) 2013-2022 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ */
+
+/**
+ * @module config
  */
 
 import type {

package/src/core/async/README.md

@@ -0,0 +1,147 @@
+The module is designed to work with asynchronous operations inside the editor.
+
+## Why
+
+Jodit editor can be created, deleted and re-created. All asynchronous operations should be destroyed along with it.
+
+If, for example, do this:
+
+```js
+const jodit = Jodit.make('#editor');
+setTimeout(() => {
+	jodit.e.on('change', () => console.log(jodit.value));
+}, 1000);
+jodit.destruct();
+```
+
+This kind of code will throw an error. At the moment the function is called, the editor will already be destructed.
+You can independently monitor such operations.
+
+For example like this:
+
+```js
+const timeout = setTimeout(() => {
+	jodit.e.on('change', () => console.log(jodit.value));
+}, 1000);
+jodit.e.on('beforeDestroy', () => clearTimeout(timeout));
+```
+
+Then there will be no error. But such code is error-prone, and you can often forget about a process.
+Therefore, the `Async` module was written. The module is intended for any kind of asynchronous operation in Jodit.
+It keeps track of its handlers, and when the parent class (Jodit) is destroyed, it will clear all threads.
+
+## Timeout/ClearTimeout
+
+For example, the code above will work without problems like this:
+
+```js
+jodit.async.setTimeout(() => {
+	jodit.e.on('change', () => console.log(jodit.value));
+}, 1000);
+jodit.destruct();
+```
+
+You can also clean up the execution of this handler yourself.
+
+```js
+const timeout = jodit.async.setTimeout(() => {}, 1000);
+jodit.async.clearTimeout(timeout);
+jodit.destruct();
+```
+
+But this is not necessary. When `jodit.destruct ()` is called, all asynchronous operations bound to this editor will be stopped.
+
+## Promise
+
+Another advantage of the module is working with promises. Promises, as well as times, can work out after the editor is destroyed.
+
+```js
+new Promise(result => {
+	fetch('index.php').then(result);
+}).then(data => {
+	//here Jodit is already destroyed
+	jodit.setEditorValue(data); // Error
+});
+
+jodit.destruct();
+```
+
+To prevent this from happening, it is better to do all operations with promises via async:
+
+```js
+jodit.async
+	.promise(result => {
+		fetch('index.php').then(result);
+	})
+	.then(data => {
+		// This handler will no longer be executed
+		jodit.setEditorValue(data);
+	});
+
+jodit.destruct();
+```
+
+## debounce/throttle
+
+Two convenient methods for well-known operations:
+
+```js
+const a = jodit.async.debounce(() => {
+	console.log('A');
+}, 100);
+a();
+// timeout 50mc
+a();
+// timeout 50mc
+a();
+a();
+// timeout 50mc
+a();
+a();
+// timeout 50mc
+a(); // A
+a();
+// timeout 150mc
+a(); // A
+```
+
+The code will be executed only once if the calls occurred more often than 100ms.
+
+```js
+const b = jodit.async.throttle(() => {
+	console.log('B');
+}, 100);
+a();
+// timeout 50mc
+a();
+// timeout 50mc
+a(); // B
+a();
+// timeout 50mc
+a();
+// timeout 50mc
+a(); // B
+```
+
+The code will be executed once per 100ms. If the method is called 100 times in one second, then it will only execute 10 of them on its body.
+
+## delay
+
+The method allows you to interrupt the execution of the script for n ms
+
+```js
+async function Run() {
+	console.log('A');
+	await jodit.async.delay(1000); // 1 sec
+	console.log('B');
+}
+```
+
+## clear
+
+You yourself can remove all asynchronous editor operations without waiting for destructuring:
+
+```js
+jodit.async.setTimeout(() => alert('Hello'), 1000);
+jodit.async.clear();
+```

package/src/core/{async.ts → async/async.ts}

@@ -1,7 +1,13 @@
 /*!
  * Jodit Editor (https://xdsoft.net/jodit/)
  * Released under MIT see LICENSE.txt in the project root for license information.
- * Copyright (c) 2013-2021 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ * Copyright (c) 2013-2022 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ */
+
+/**
+ * [[include:core/async/README.md]]
+ * @packageDocumentation
+ * @module async
  */
 
 import type {
@@ -10,7 +16,7 @@ import type {
 	IAsyncParams,
 	ITimeout,
 	RejectablePromise
-} from '../types';
+} from '../../types';
 import {
 	setTimeout,
 	clearTimeout,
@@ -19,11 +25,15 @@ import {
 	isPromise,
 	isString,
 	isNumber
-} from './helpers/';
+} from '../helpers/';
 
 export class Async implements IAsync {
 	private timers: Map<number | string | Function, number> = new Map();
 
+	delay(timeout: number | IAsyncParams): RejectablePromise<void> {
+		return this.promise(resolve => this.setTimeout(resolve, timeout));
+	}
+
 	setTimeout(
 		callback: (...args: any[]) => void,
 		timeout: number | IAsyncParams,
@@ -77,11 +87,10 @@ export class Async implements IAsync {
 	 * @example
 	 * ```javascript
 	 * var jodit = new Jodit('.editor');
-	 *	jodit.e.on('mousemove', jodit.async.debounce(function() {
-	 *     // Do expensive things
+	 * jodit.e.on('mousemove', jodit.async.debounce(() => {
+	 * 	// Do expensive things
 	 * }, 100));
 	 * ```
-	 *
 	 */
 	debounce(
 		fn: CallbackFunction,
@@ -152,7 +161,7 @@ export class Async implements IAsync {
 	 * ```javascript
 	 * var jodit = new Jodit('.editor');
 	 * jodit.e.on(document.body, 'scroll', jodit.async.throttle(function() {
-	 *     // Do expensive things
+	 * 	// Do expensive things
 	 * }, 100));
 	 * ```
 	 */

package/src/core/async/index.ts

@@ -0,0 +1,11 @@
+/*!
+ * Jodit Editor (https://xdsoft.net/jodit/)
+ * Released under MIT see LICENSE.txt in the project root for license information.
+ * Copyright (c) 2013-2022 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ */
+
+/**
+ * @module async
+ */
+
+export * from './async';

package/src/core/component/README.md

@@ -0,0 +1,110 @@
+Every Jodit element inherits from [[Component]], and implements the [[IComponent]] interface accordingly.
+
+Such elements have a name
+
+```js
+const jodit = Jodit.male('#editor');
+console.log(jodit.componentName)
+console.log(jodit.statusbar.componentName)
+console.log(jodit.filebrowser.componentName)
+console.log(jodit.uploader.componentName)
+```
+
+And also each component has its current [[STATUSES | status]]:
+
+```js
+const jodit = Jodit.male('#editor');
+console.log(jodit.componentStatus)
+```
+
+You can work on changes in the status of a component through the decorator [[decorators/hook]]
+either through the method [[Component.prototype.hookStatus]]
+
+```ts
+import { Component } from 'jodit/src/core/component'
+
+export class SomeComponent extends Component {}
+const cmp = new SomeComponent();
+
+cmp.hookStatus('ready', () => {
+	console.log('Hello world on ready = )')
+})
+```
+
+To set the status, it is enough to call the method [[Component.prototype.setStatus]]
+
+```ts
+import { Component } from 'jodit/src/core/component'
+
+export class SomeComponent extends Component {}
+const cmp = new SomeComponent();
+cmp.setStatus('ready')
+```
+
+The component itself can automatically set the ready status:
+
+```ts
+import type { IJodit } from 'jodit/src/types'
+import { Component } from 'jodit/src/core/component'
+
+export class SomeComponent extends Component {
+  constructor(jodit: IJodit) {
+    super(jodit);
+    cmp.setStatus('ready')
+  }
+}
+
+const cmp = new SomeComponent();
+console.log(cmp.isReady)
+```
+But it’s better not to do this, because with inheritance, such a component will be “ready” ahead of time:
+
+```ts
+import type { IJodit, IStatusBar } from 'jodit/src/types'
+import { Component } from 'jodit/src/core/component'
+import { StatusBar } from 'jodit/src/modules';
+
+export class SomeComponent extends Component {
+  constructor(jodit: IJodit) {
+    super(jodit);
+    cmp.setStatus('ready')
+  }
+}
+
+export class SomeAnotherComponent extends SomeComponent {
+  public status: IStatusBar;
+
+  constructor(jodit: IJodit) {
+    super(jodit);
+	  console.log(this.isReady) // true
+    // Errors are possible here, since the status of the component is already 'ready' but you have not yet initialized its fields
+    this.status = new StatusBar(jodit)
+  }
+}
+```
+
+Therefore, it is better to use a decorator [[core/decorators/component]]
+
+```ts
+import type { IJodit, IStatusBar } from 'jodit/src/types'
+import { Component } from 'jodit/src/core/component'
+import { StatusBar } from 'jodit/src/modules';
+import { component } from 'jodit/src/core/decorators';
+
+@component()
+export class SomeComponent extends Component {}
+
+@component()
+export class SomeAnotherComponent extends SomeComponent {
+  public status: IStatusBar;
+
+  constructor(jodit: IJodit) {
+    super(jodit);
+	  console.log(this.isReady) // false
+    this.status = new StatusBar(jodit)
+  }
+}
+
+const cmp = new SomeAnotherComponent();
+console.log(cmp.isReady) // true
+```

package/src/core/component/component.ts

@@ -1,7 +1,13 @@
 /*!
  * Jodit Editor (https://xdsoft.net/jodit/)
  * Released under MIT see LICENSE.txt in the project root for license information.
- * Copyright (c) 2013-2021 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ * Copyright (c) 2013-2022 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ */
+
+/**
+ * [[include:core/component/README.md]]
+ * @packageDocumentation
+ * @module component
  */
 
 import type {

package/src/core/component/index.ts

@@ -1,7 +1,11 @@
 /*!
  * Jodit Editor (https://xdsoft.net/jodit/)
  * Released under MIT see LICENSE.txt in the project root for license information.
- * Copyright (c) 2013-2021 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ * Copyright (c) 2013-2022 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ */
+
+/**
+ * @module component
  */
 
 export * from './statuses';

package/src/core/component/statuses.ts

@@ -1,7 +1,11 @@
 /*!
  * Jodit Editor (https://xdsoft.net/jodit/)
  * Released under MIT see LICENSE.txt in the project root for license information.
- * Copyright (c) 2013-2021 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ * Copyright (c) 2013-2022 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ */
+
+/**
+ * @module component
  */
 
 export const STATUSES = {

package/src/core/component/view-component.ts

@@ -1,7 +1,11 @@
 /*!
  * Jodit Editor (https://xdsoft.net/jodit/)
  * Released under MIT see LICENSE.txt in the project root for license information.
- * Copyright (c) 2013-2021 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ * Copyright (c) 2013-2022 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ */
+
+/**
+ * @module component
  */
 
 import type { IViewBased, IViewComponent } from '../../types';

package/src/core/constants.ts

@@ -1,7 +1,11 @@
 /*!
  * Jodit Editor (https://xdsoft.net/jodit/)
  * Released under MIT see LICENSE.txt in the project root for license information.
- * Copyright (c) 2013-2021 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ * Copyright (c) 2013-2022 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ */
+
+/**
+ * @module constants
  */
 
 import type { IDictionary } from '../types';

package/src/core/create/README.md

@@ -0,0 +1,57 @@
+Every internal DOM node of both the editor interface and the editor content itself must be created through this module.
+This is due to the fact that the interface can be shown in an iframe, or another window.
+And in this case, you need to create its elements using the document from this window.
+In order not to worry about it yourself, this module was created.
+
+For example, we initialize the editor in iframe mode:
+
+```js
+const jodit = Jodit.make('#editor', { iframe: true });
+```
+
+In this case, in plugins, to insert a value, you would have to write the following construction:
+
+```js
+const p = jodit.iframe.contentWindow.document.createElement('p');
+jodit.s.insertNode(p);
+```
+
+In order not to think about it, the [[IJodit]] interface has a field [[Jodit.createInside]] and [[Jodit.create]].
+Both fields are [[ICreate]] instances, but the first should be used for creating elements inside the editor.
+And the second is for the editor interface.
+
+The previous example, regardless of the operating mode, will be like this:
+
+```js
+const p = jodit.createInside.element('p');
+jodit.s.insertNode(p);
+```
+
+This method of creating DOM elements has one more advantage, you can add the option [[Config.createAttributes]]
+And then, for each created element, the attributes you specified will already be set:
+
+```js
+const jodit = Jodit.make('#editor', {
+	createAttributes: {
+		p: {
+			style: 'color: red'
+		},
+		a: a => {
+			a.title = 'Some title';
+		}
+	}
+});
+
+const p = jodit.createInside.element('p');
+console.log(p.style.cssText) // color: red
+
+const a = jodit.createInside.element('a');
+console.log(a.title) // Some title
+```
+
+To create DOM elements from text, you should also use this module:
+
+```js
+const p = jodit.createInside.fromHTML('<p>text</p>');
+jodit.s.insertNode(p);
+```

package/src/core/{create.ts → create/create.ts}

@@ -1,7 +1,13 @@
 /*!
  * Jodit Editor (https://xdsoft.net/jodit/)
  * Released under MIT see LICENSE.txt in the project root for license information.
- * Copyright (c) 2013-2021 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ * Copyright (c) 2013-2022 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ */
+
+/**
+ * [[include:core/create/README.md]]
+ * @packageDocumentation
+ * @module create
  */
 
 import type {
@@ -11,7 +17,7 @@ import type {
 	ICreate,
 	CanUndef,
 	NodeFunction
-} from '../types';
+} from '../../types';
 
 import {
 	isPlainObject,
@@ -20,10 +26,10 @@ import {
 	refs,
 	isString,
 	attr
-} from './helpers/';
+} from '../helpers/';
 
-import { Dom } from './dom';
-import { INVISIBLE_SPACE } from './constants';
+import { Dom } from '../dom';
+import { INVISIBLE_SPACE } from '../constants';
 
 export class Create implements ICreate {
 	private get doc(): Document {

package/src/core/create/index.ts

@@ -0,0 +1,11 @@
+/*!
+ * Jodit Editor (https://xdsoft.net/jodit/)
+ * Released under MIT see LICENSE.txt in the project root for license information.
+ * Copyright (c) 2013-2022 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ */
+
+/**
+ * @module create
+ */
+
+export * from './create';

package/src/core/decorators/README.md

@@ -0,0 +1,4 @@
+# Jodit component UI decorators
+
+Decorators are designed to make it easier to work with UI components.
+Adding event handlers, state changes, and component status.

package/src/core/decorators/cache/README.md

@@ -0,0 +1,17 @@
+The decorator allows you to cache the result of executing any method of the UI component.
+
+```typescript
+@component()
+class UIComponent extends UIElement {
+  @cache()
+  someHeavyMethod(param1, param2) {
+    return someHeaveCalculation(param1, param2);
+  }
+}
+
+const elm = new UIComponent(jodit);
+elm.someHeavyMethod(1, 2);
+elm.someHeavyMethod(1, 2);
+elm.someHeavyMethod(1, 2); // someHeaveCalculation will execute only once
+elm.someHeavyMethod(2, 2); // someHeaveCalculation will execute again
+```

package/src/core/decorators/{cache.ts → cache/cache.ts}

@@ -1,11 +1,17 @@
 /*!
  * Jodit Editor (https://xdsoft.net/jodit/)
  * Released under MIT see LICENSE.txt in the project root for license information.
- * Copyright (c) 2013-2021 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
+ * Copyright (c) 2013-2022 Valeriy Chupurnov. All rights reserved. https://xdsoft.net
  */
 
-import { error } from '../helpers';
-import type { IDictionary } from '../../types';
+/**
+ * [[include:core/decorators/cache/README.md]]
+ * @packageDocumentation
+ * @module decorators/cache
+ */
+
+import { error } from '../../helpers';
+import type { IDictionary } from '../../../types';
 
 export interface CachePropertyDescriptor<T, R> extends PropertyDescriptor {
 	get?: (this: T) => R;