Caret API (codex-team#605)

* Caret API

* Check block existence before setting the caret

* Update docs/api.md

Co-Authored-By: gohabereg <gohabereg@users.noreply.github.com>

* Update docs/api.md

Co-Authored-By: gohabereg <gohabereg@users.noreply.github.com>

* Update docs/api.md

Co-Authored-By: gohabereg <gohabereg@users.noreply.github.com>

* Update CHANGELOG.md

dist/codex-editor.licenses.txt

@@ -76,32 +76,6 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 regenerator-runtime
 MIT
 
-@babel/register
-MIT
-MIT License
-
-Copyright (c) 2014-2018 Sebastian McKenzie <sebmck@gmail.com>
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-
 codex-notifier
 MIT
 MIT License
@@ -402,3 +376,29 @@ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+@babel/register
+MIT
+MIT License
+
+Copyright (c) 2014-2018 Sebastian McKenzie <sebmck@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

docs/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+### 2.8.0
+
+- `Imporvements` *API* - Added [API methods](api.md#caretapi) to manage caret position
+
+### 2.7.32
+
+- `Improvements` *Types* - TypeScript types sre updated
+
 ### 2.7.31
 
 - `Fix` Caret now goes through <input> elements without `type` attribute

docs/api.md

@@ -1,5 +1,6 @@
 # CodeX Editor API
 
+
 Blocks have access to the public methods provided by CodeX Editor API Module. Plugin and Tune Developers
 can use Editor API as they want.
 
@@ -8,7 +9,7 @@ can use Editor API as they want.
 Common API interface.
 
 ```js
-export interface IAPI {
+export interface API {
    blocks: IBlocksAPI;
    caret: ICaretAPI;
    sanitizer: ISanitizerAPI;
@@ -17,7 +18,7 @@ export interface IAPI {
  }
  ```
 
-#### IBlocksAPI
+#### BlocksAPI
 
 Methods that working with Blocks
 
@@ -35,7 +36,7 @@ Methods that working with Blocks
 
 `insertNewBlock()` - insert new Block after working place
 
-#### ISanitizerAPI
+#### SanitizerAPI
 
 `clean(taintString, config)` - method uses HTMLJanitor to clean taint string.
 
@@ -56,15 +57,15 @@ let customConfig = {
 this.api.sanitizer.clean(taintString, customConfig);
 ```
 
-### IToolbarAPI
+### ToolbarAPI
 
 Methods that working with Toolbar
 
 `open()` - opens toolbar
 
 `close()` - closes toolbar, toolbox and blockSettings if they are opened
 
-### IEventsAPI
+### EventsAPI
 
 Methods that allows to subscribe on CodeX Editor events
 
@@ -74,14 +75,41 @@ Methods that allows to subscribe on CodeX Editor events
 
 `emit(eventName: string, data: object)` - fires all subscribed callbacks with passed data
 
-### IListenerAPI
+### ListenerAPI
 
 Methods that allows to work with DOM listener. Useful when you forgot to remove listener. Module collects all listeners and destroys automatically
 
 `on(element: HTMLElement, eventType: string, handler: Function, useCapture?: boolean)` - add event listener to HTML element
 
 `off(element: HTMLElement, eventType: string, handler: Function)` - remove event handler from HTML element
 
+
+### CaretAPI
+
+Methods to manage caret position.
+
+Each method accept `position` and `offset` parameters. `Offset` should be used to shift caret by passed amount of characters.
+
+`Position` can be one of the following values:
+
+| Value     | Description 
+| --------- | ----------- 
+| `start`   | Caret will be set at the Block's beginning
+| `end`     | Caret will be set at the Block end
+| `default` | More or less emulates browser behaviour, in most cases behaves as `start`  
+
+Each method returns `boolean` value: true if caret is set successfully or false otherwise (e.g. when there is no Block at index);
+
+`setToFirstBlock(position?: 'end'|'start'|'default', offset?: number): boolean;` — set caret to the first Block
+
+`setToLastBlock(position?: 'end'|'start'|'default', offset?: number): boolean;` — set caret to the last Block
+
+`setToNextBlock(position?: 'end'|'start'|'default', offset?: number): boolean;` — set caret to the next Block
+
+`setToPreviousBlock(position?: 'end'|'start'|'default', offset?: number): boolean;` — set caret to the previous Block
+
+`setToBlock(index: number, position?: 'end'|'start'|'default', offset?: number): boolean;` — set caret to the Block by passed `index`
+
 ### NotifierAPI
 
 If you need to show any messages for success or failure events you can use notifications module.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex.editor",
-  "version": "2.7.32",
+  "version": "2.8.0",
   "description": "CodeX Editor. Native JS, based on API and Open Source",
   "main": "dist/codex-editor.js",
   "types": "./types/index.d.ts",

src/components/modules/api/caret.ts

@@ -1,6 +1,5 @@
 import Module from '../../__module';
 import {Caret} from '../../../../types/api';
-import {ModuleConfig} from '../../../types-internal/module-config';
 
 /**
  * @class CaretAPI
@@ -12,6 +11,105 @@ export default class CaretAPI extends Module {
    * @return {Caret}
    */
   get methods(): Caret {
-    return {};
+    return {
+      setToFirstBlock: this.setToFirstBlock,
+      setToLastBlock: this.setToLastBlock,
+      setToPreviousBlock: this.setToPreviousBlock,
+      setToNextBlock: this.setToNextBlock,
+      setToBlock: this.setToBlock,
+    };
+  }
+
+  /**
+   * Sets caret to the first Block
+   *
+   * @param {string} position - position where to set caret
+   * @param {number} offset - caret offset
+   *
+   * @return {boolean}
+   */
+  private setToFirstBlock = (position: string = this.Editor.Caret.positions.DEFAULT, offset: number = 0): boolean => {
+    if (!this.Editor.BlockManager.firstBlock) {
+      return false;
+    }
+
+    this.Editor.Caret.setToBlock(this.Editor.BlockManager.firstBlock, position, offset);
+    return true;
+  }
+
+  /**
+   * Sets caret to the last Block
+   *
+   * @param {string} position - position where to set caret
+   * @param {number} offset - caret offset
+   *
+   * @return {boolean}
+   */
+  private setToLastBlock = (position: string = this.Editor.Caret.positions.DEFAULT, offset: number = 0): boolean => {
+    if (!this.Editor.BlockManager.lastBlock) {
+      return false;
+    }
+
+    this.Editor.Caret.setToBlock(this.Editor.BlockManager.lastBlock, position, offset);
+    return true;
+  }
+
+  /**
+   * Sets caret to the previous Block
+   *
+   * @param {string} position - position where to set caret
+   * @param {number} offset - caret offset
+   *
+   * @return {boolean}
+   */
+  private setToPreviousBlock = (
+    position: string = this.Editor.Caret.positions.DEFAULT,
+    offset: number = 0,
+  ): boolean => {
+    if (!this.Editor.BlockManager.previousBlock) {
+      return false;
+    }
+
+    this.Editor.Caret.setToBlock(this.Editor.BlockManager.previousBlock, position, offset);
+    return true;
+  }
+
+  /**
+   * Sets caret to the next Block
+   *
+   * @param {string} position - position where to set caret
+   * @param {number} offset - caret offset
+   *
+   * @return {boolean}
+   */
+  private setToNextBlock = (position: string = this.Editor.Caret.positions.DEFAULT, offset: number = 0): boolean => {
+    if (!this.Editor.BlockManager.nextBlock) {
+      return false;
+    }
+
+    this.Editor.Caret.setToBlock(this.Editor.BlockManager.nextBlock, position, offset);
+    return true;
+  }
+
+  /**
+   * Sets caret to the Block by passed index
+   *
+   * @param {number} index - index of Block where to set caret
+   * @param {string} position - position where to set caret
+   * @param {number} offset - caret offset
+   *
+   * @return {boolean}
+   */
+  private setToBlock = (
+    index: number,
+    position: string = this.Editor.Caret.positions.DEFAULT,
+    offset: number = 0,
+  ): boolean => {
+    if (!this.Editor.BlockManager.blocks[index]) {
+      return false;
+    }
+
+    this.Editor.Caret.setToBlock(this.Editor.BlockManager.blocks[index], position, offset);
+    return true;
   }
 }

src/components/modules/blockManager.ts

@@ -44,6 +44,14 @@ export default class BlockManager extends Module {
     this._currentBlockIndex = newIndex;
   }
 
+  /**
+   * returns first Block
+   * @return {Block}
+   */
+  public get firstBlock(): Block {
+    return this._blocks[0];
+  }
+
   /**
    * returns last Block
    * @return {Block}

types/api/caret.d.ts

@@ -1,6 +1,56 @@
 /**
  * Describes Editor`s caret API
- *
- * TODO
  */
-export interface Caret {}
+export interface Caret {
+
+  /**
+   * Sets caret to the first Block
+   *
+   * @param {string} position - position where to set caret
+   * @param {number} offset - caret offset
+   *
+   * @return {boolean}
+   */
+  setToFirstBlock(position?: 'end'|'start'|'default', offset?: number): boolean;
+
+  /**
+   * Sets caret to the last Block
+   *
+   * @param {string} position - position where to set caret
+   * @param {number} offset - caret offset
+   *
+   * @return {boolean}
+   */
+  setToLastBlock(position?: 'end'|'start'|'default', offset?: number): boolean;
+
+  /**
+   * Sets caret to the previous Block
+   *
+   * @param {string} position - position where to set caret
+   * @param {number} offset - caret offset
+   *
+   * @return {boolean}
+   */
+  setToPreviousBlock(position?: 'end'|'start'|'default', offset?: number): boolean;
+
+  /**
+   * Sets caret to the next Block
+   *
+   * @param {string} position - position where to set caret
+   * @param {number} offset - caret offset
+   *
+   * @return {boolean}
+   */
+  setToNextBlock(position?: 'end'|'start'|'default', offset?: number): boolean;
+
+  /**
+   * Sets caret to the Block by passed index
+   *
+   * @param {number} index - index of Block where to set caret
+   * @param {string} position - position where to set caret
+   * @param {number} offset - caret offset
+   *
+   * @return {boolean}
+   */
+  setToBlock(index: number, position?: 'end'|'start'|'default', offset?: number): boolean;
+}