@jackuait/blok 0.4.1-beta.1 → 0.4.1-beta.12

package/src/components/modules/api/blocks.ts

@@ -0,0 +1,377 @@
+import type { BlockAPI as BlockAPIInterface, Blocks } from '../../../../types/api';
+import type { BlockToolData, OutputBlockData, OutputData, ToolConfig } from '../../../../types';
+import { logLabeled } from './../../utils';
+import { BlockAPI } from '../../block/api';
+import { Module } from '../../__module';
+import { Block } from '../../block';
+import { capitalize } from '../../utils';
+import type { BlockTuneData } from '../../../../types/block-tunes/block-tune-data';
+
+/**
+ * @class BlocksAPI
+ * provides with methods working with Block
+ */
+export class BlocksAPI extends Module {
+  /**
+   * Available methods
+   * @returns {Blocks}
+   */
+  public get methods(): Blocks {
+    return {
+      clear: (): Promise<void> => this.clear(),
+      render: (data: OutputData): Promise<void> => this.render(data),
+      renderFromHTML: (data: string): Promise<void> => this.renderFromHTML(data),
+      delete: (index?: number): Promise<void> => this.delete(index),
+      move: (toIndex: number, fromIndex?: number): void => this.move(toIndex, fromIndex),
+      getBlockByIndex: (index: number): BlockAPIInterface | undefined => this.getBlockByIndex(index),
+      getById: (id: string): BlockAPIInterface | null => this.getById(id),
+      getCurrentBlockIndex: (): number => this.getCurrentBlockIndex(),
+      getBlockIndex: (id: string): number | undefined => this.getBlockIndex(id),
+      getBlocksCount: (): number => this.getBlocksCount(),
+      getBlockByElement: (element: HTMLElement) => this.getBlockByElement(element),
+      insert: this.insert,
+      insertMany: this.insertMany,
+      update: this.update,
+      composeBlockData: this.composeBlockData,
+      convert: this.convert,
+      stopBlockMutationWatching: (index: number): void => this.stopBlockMutationWatching(index),
+    };
+  }
+
+  /**
+   * Returns Blocks count
+   * @returns {number}
+   */
+  public getBlocksCount(): number {
+    return this.Blok.BlockManager.blocks.length;
+  }
+
+  /**
+   * Returns current block index
+   * @returns {number}
+   */
+  public getCurrentBlockIndex(): number {
+    return this.Blok.BlockManager.currentBlockIndex;
+  }
+
+  /**
+   * Returns the index of Block by id;
+   * @param id - block id
+   */
+  public getBlockIndex(id: string): number | undefined {
+    const block = this.Blok.BlockManager.getBlockById(id);
+
+    if (!block) {
+      logLabeled('There is no block with id `' + id + '`', 'warn');
+
+      return;
+    }
+
+    return this.Blok.BlockManager.getBlockIndex(block);
+  }
+
+  /**
+   * Returns BlockAPI object by Block index
+   * @param {number} index - index to get
+   */
+  public getBlockByIndex(index: number): BlockAPIInterface | undefined {
+    const block = this.Blok.BlockManager.getBlockByIndex(index);
+
+    if (block === undefined) {
+      logLabeled('There is no block at index `' + index + '`', 'warn');
+
+      return;
+    }
+
+    return new BlockAPI(block);
+  }
+
+  /**
+   * Returns BlockAPI object by Block id
+   * @param id - id of block to get
+   */
+  public getById(id: string): BlockAPIInterface | null {
+    const block = this.Blok.BlockManager.getBlockById(id);
+
+    if (block === undefined) {
+      logLabeled('There is no block with id `' + id + '`', 'warn');
+
+      return null;
+    }
+
+    return new BlockAPI(block);
+  }
+
+  /**
+   * Get Block API object by any child html element
+   * @param element - html element to get Block by
+   */
+  public getBlockByElement(element: HTMLElement): BlockAPIInterface | undefined {
+    const block = this.Blok.BlockManager.getBlock(element);
+
+    if (block === undefined) {
+      logLabeled('There is no block corresponding to element `' + element + '`', 'warn');
+
+      return;
+    }
+
+    return new BlockAPI(block);
+  }
+
+  /**
+   * Move block from one index to another
+   * @param {number} toIndex - index to move to
+   * @param {number} fromIndex - index to move from
+   */
+  public move(toIndex: number, fromIndex?: number): void {
+    this.Blok.BlockManager.move(toIndex, fromIndex);
+  }
+
+  /**
+   * Deletes Block
+   * @param {number} blockIndex - index of Block to delete
+   */
+  public async delete(blockIndex: number = this.Blok.BlockManager.currentBlockIndex): Promise<void> {
+    const block = this.Blok.BlockManager.getBlockByIndex(blockIndex);
+
+    if (block === undefined) {
+      logLabeled(`There is no block at index \`${blockIndex}\``, 'warn');
+
+      return;
+    }
+
+    try {
+      await this.Blok.BlockManager.removeBlock(block);
+    } catch (error: unknown) {
+      logLabeled(error as unknown as string, 'warn');
+
+      return;
+    }
+
+    /**
+     * in case of last block deletion
+     * Insert the new default empty block
+     */
+    if (this.Blok.BlockManager.blocks.length === 0) {
+      this.Blok.BlockManager.insert();
+    }
+
+    /**
+     * After Block deletion currentBlock is updated
+     */
+    if (this.Blok.BlockManager.currentBlock) {
+      this.Blok.Caret.setToBlock(this.Blok.BlockManager.currentBlock, this.Blok.Caret.positions.END);
+    }
+
+    this.Blok.Toolbar.close();
+  }
+
+  /**
+   * Clear Blok's area
+   */
+  public async clear(): Promise<void> {
+    await this.Blok.BlockManager.clear(true);
+    this.Blok.InlineToolbar.close();
+  }
+
+  /**
+   * Fills Blok with Blocks data
+   * @param {OutputData} data — Saved Blok data
+   */
+  public async render(data: OutputData): Promise<void> {
+    if (data === undefined || data.blocks === undefined) {
+      throw new Error('Incorrect data passed to the render() method');
+    }
+
+    /**
+     * Semantic meaning of the "render" method: "Display the new document over the existing one that stays unchanged"
+     * So we need to disable modifications observer temporarily
+     */
+    this.Blok.ModificationsObserver.disable();
+
+    await this.Blok.BlockManager.clear();
+    await this.Blok.Renderer.render(data.blocks);
+
+    this.Blok.ModificationsObserver.enable();
+  }
+
+  /**
+   * Render passed HTML string
+   * @param {string} data - HTML string to render
+   * @returns {Promise<void>}
+   */
+  public async renderFromHTML(data: string): Promise<void> {
+    await this.Blok.BlockManager.clear();
+
+    return this.Blok.Paste.processText(data, true);
+  }
+
+  /**
+   * Insert new Block and returns it's API
+   * @param {string} type — Tool name
+   * @param {BlockToolData} data — Tool data to insert
+   * @param {ToolConfig} _config — Tool config
+   * @param {number?} index — index where to insert new Block
+   * @param {boolean?} needToFocus - flag to focus inserted Block
+   * @param replace - pass true to replace the Block existed under passed index
+   * @param {string} id — An optional id for the new block. If omitted then the new id will be generated
+   */
+  public insert = (
+    type?: string,
+    data: BlockToolData = {},
+    _config: ToolConfig = {},
+    index?: number,
+    needToFocus?: boolean,
+    replace?: boolean,
+    id?: string
+  ): BlockAPIInterface => {
+    const tool = type ?? (this.config.defaultBlock as string | undefined);
+
+    const insertedBlock = this.Blok.BlockManager.insert({
+      id,
+      tool,
+      data,
+      index,
+      needToFocus,
+      replace,
+    });
+
+    return new BlockAPI(insertedBlock);
+  };
+
+  /**
+   * Creates data of an empty block with a passed type.
+   * @param toolName - block tool name
+   */
+  public composeBlockData = async (toolName: string): Promise<BlockToolData> => {
+    const tool = this.Blok.Tools.blockTools.get(toolName);
+
+    if (tool === undefined) {
+      throw new Error(`Block Tool with type "${toolName}" not found`);
+    }
+
+    const block = new Block({
+      tool,
+      api: this.Blok.API,
+      readOnly: true,
+      data: {},
+      tunesData: {},
+    });
+
+    return block.data;
+  };
+
+  /**
+   * Updates block data by id
+   * @param id - id of the block to update
+   * @param data - (optional) the new data
+   * @param tunes - (optional) tune data
+   */
+  public update = async (id: string, data?: Partial<BlockToolData>, tunes?: {[name: string]: BlockTuneData}): Promise<BlockAPIInterface> => {
+    const { BlockManager } = this.Blok;
+    const block = BlockManager.getBlockById(id);
+
+    if (block === undefined) {
+      throw new Error(`Block with id "${id}" not found`);
+    }
+
+    const updatedBlock = await BlockManager.update(block, data, tunes);
+
+    return new BlockAPI(updatedBlock);
+  };
+
+  /**
+   * Converts block to another type. Both blocks should provide the conversionConfig.
+   * @param id - id of the existing block to convert. Should provide 'conversionConfig.export' method
+   * @param newType - new block type. Should provide 'conversionConfig.import' method
+   * @param dataOverrides - optional data overrides for the new block
+   * @throws Error if conversion is not possible
+   */
+  private convert = async (id: string, newType: string, dataOverrides?: BlockToolData): Promise<BlockAPIInterface> => {
+    const { BlockManager, Tools } = this.Blok;
+    const blockToConvert = BlockManager.getBlockById(id);
+
+    if (!blockToConvert) {
+      throw new Error(`Block with id "${id}" not found`);
+    }
+
+    const originalBlockTool = Tools.blockTools.get(blockToConvert.name);
+    const targetBlockTool = Tools.blockTools.get(newType);
+
+    if (!targetBlockTool) {
+      throw new Error(`Block Tool with type "${newType}" not found`);
+    }
+
+    const originalBlockConvertable = originalBlockTool?.conversionConfig?.export !== undefined;
+    const targetBlockConvertable = targetBlockTool.conversionConfig?.import !== undefined;
+
+    if (originalBlockConvertable && targetBlockConvertable) {
+      const newBlock = await BlockManager.convert(blockToConvert, newType, dataOverrides);
+
+      return new BlockAPI(newBlock);
+    } else {
+      const unsupportedBlockTypes = [
+        !originalBlockConvertable ? capitalize(blockToConvert.name) : false,
+        !targetBlockConvertable ? capitalize(newType) : false,
+      ].filter(Boolean).join(' and ');
+
+      throw new Error(`Conversion from "${blockToConvert.name}" to "${newType}" is not possible. ${unsupportedBlockTypes} tool(s) should provide a "conversionConfig"`);
+    }
+  };
+
+
+  /**
+   * Inserts several Blocks to a specified index
+   * @param blocks - blocks data to insert
+   * @param index - index to insert the blocks at
+   */
+  private insertMany = (
+    blocks: OutputBlockData[],
+    index: number = this.Blok.BlockManager.blocks.length - 1
+  ): BlockAPIInterface[] => {
+    this.validateIndex(index);
+
+    const blocksToInsert = blocks.map(({ id, type, data }) => {
+      return this.Blok.BlockManager.composeBlock({
+        id,
+        tool: type || (this.config.defaultBlock as string),
+        data,
+      });
+    });
+
+    this.Blok.BlockManager.insertMany(blocksToInsert, index);
+
+    return blocksToInsert.map((block) => new BlockAPI(block));
+  };
+
+  /**
+   * Stops mutation watching on a block at the specified index.
+   * This is used to prevent spurious block-changed events during block replacement.
+   * @param index - index of the block to stop watching
+   */
+  private stopBlockMutationWatching(index: number): void {
+    const block = this.Blok.BlockManager.getBlockByIndex(index);
+
+    if (block !== undefined) {
+      block.unwatchBlockMutations();
+    }
+  }
+
+  /**
+   * Validated block index and throws an error if it's invalid
+   * @param index - index to validate
+   */
+  private validateIndex(index: unknown): void {
+    if (typeof index !== 'number') {
+      throw new Error('Index should be a number');
+    }
+
+    if (index < 0) {
+      throw new Error(`Index should be greater than or equal to 0`);
+    }
+
+    if (index === null) {
+      throw new Error(`Index should be greater than or equal to 0`);
+    }
+  }
+}

package/src/components/modules/api/caret.ts

@@ -0,0 +1,125 @@
+import type { BlockAPI, Caret } from '../../../../types/api';
+import { Module } from '../../__module';
+import { resolveBlock } from '../../utils/api';
+
+/**
+ * @class CaretAPI
+ * provides with methods to work with caret
+ */
+export class CaretAPI extends Module {
+  /**
+   * Available methods
+   * @returns {Caret}
+   */
+  public get methods(): Caret {
+    return {
+      setToFirstBlock: this.setToFirstBlock,
+      setToLastBlock: this.setToLastBlock,
+      setToPreviousBlock: this.setToPreviousBlock,
+      setToNextBlock: this.setToNextBlock,
+      setToBlock: this.setToBlock,
+      focus: this.focus,
+    };
+  }
+
+  /**
+   * Sets caret to the first Block
+   * @param {string} position - position where to set caret
+   * @param {number} offset - caret offset
+   * @returns {boolean}
+   */
+  private setToFirstBlock = (position: string = this.Blok.Caret.positions.DEFAULT, offset = 0): boolean => {
+    if (!this.Blok.BlockManager.firstBlock) {
+      return false;
+    }
+
+    this.Blok.Caret.setToBlock(this.Blok.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
+   * @returns {boolean}
+   */
+  private setToLastBlock = (position: string = this.Blok.Caret.positions.DEFAULT, offset = 0): boolean => {
+    if (!this.Blok.BlockManager.lastBlock) {
+      return false;
+    }
+
+    this.Blok.Caret.setToBlock(this.Blok.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
+   * @returns {boolean}
+   */
+  private setToPreviousBlock = (
+    position: string = this.Blok.Caret.positions.DEFAULT,
+    offset = 0
+  ): boolean => {
+    if (!this.Blok.BlockManager.previousBlock) {
+      return false;
+    }
+
+    this.Blok.Caret.setToBlock(this.Blok.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
+   * @returns {boolean}
+   */
+  private setToNextBlock = (position: string = this.Blok.Caret.positions.DEFAULT, offset = 0): boolean => {
+    if (!this.Blok.BlockManager.nextBlock) {
+      return false;
+    }
+
+    this.Blok.Caret.setToBlock(this.Blok.BlockManager.nextBlock, position, offset);
+
+    return true;
+  };
+
+  /**
+   * Sets caret to the Block by passed index
+   * @param blockOrIdOrIndex - either BlockAPI or Block id or Block index
+   * @param position - position where to set caret
+   * @param offset - caret offset
+   * @returns {boolean}
+   */
+  private setToBlock = (
+    blockOrIdOrIndex: BlockAPI | BlockAPI['id'] | number,
+    position: string = this.Blok.Caret.positions.DEFAULT,
+    offset = 0
+  ): boolean => {
+    const block = resolveBlock(blockOrIdOrIndex, this.Blok);
+    if (block === undefined) {
+      return false;
+    }
+
+    this.Blok.Caret.setToBlock(block, position, offset);
+
+    return true;
+  };
+
+  /**
+   * Sets caret to the Blok
+   * @param {boolean} atEnd - if true, set Caret to the end of the Blok
+   * @returns {boolean}
+   */
+  private focus = (atEnd = false): boolean => {
+    if (atEnd) {
+      return this.setToLastBlock(this.Blok.Caret.positions.END);
+    }
+
+    return this.setToFirstBlock(this.Blok.Caret.positions.START);
+  };
+}

package/src/components/modules/api/events.ts

@@ -0,0 +1,51 @@
+import { Module } from '../../__module';
+import type { Events } from '../../../../types/api';
+import type { BlokEventMap } from '../../events';
+
+/**
+ * @class EventsAPI
+ * provides with methods working with Toolbar
+ */
+export class EventsAPI extends Module {
+  /**
+   * Available methods
+   * @returns {Events}
+   */
+  public get methods(): Events {
+    return {
+      emit: (eventName: keyof BlokEventMap, data: BlokEventMap[keyof BlokEventMap] | undefined): void => this.emit(eventName, data),
+      off: (eventName: keyof BlokEventMap, callback: (data?: unknown) => void): void => this.off(eventName, callback),
+      on: (eventName: keyof BlokEventMap, callback: () => void): void => this.on(eventName, callback),
+    };
+  }
+
+  /**
+   * Subscribe on Events
+   * @param {string} eventName - event name to subscribe
+   * @param {Function} callback - event handler
+   */
+  public on(eventName: keyof BlokEventMap, callback: (data?: unknown) => void): void {
+    this.eventsDispatcher.on(eventName, callback);
+  }
+
+  /**
+   * Emit event with data
+   * @param {string} eventName - event to emit
+   * @param {object} data - event's data
+   */
+  public emit(eventName: keyof BlokEventMap, data: BlokEventMap[keyof BlokEventMap] | undefined): void {
+    this.eventsDispatcher.emit(
+      eventName,
+      data
+    );
+  }
+
+  /**
+   * Unsubscribe from Event
+   * @param {string} eventName - event to unsubscribe
+   * @param {Function} callback - event handler
+   */
+  public off(eventName: keyof BlokEventMap, callback: (data?: unknown) => void): void {
+    this.eventsDispatcher.off(eventName, callback);
+  }
+}

package/src/components/modules/api/history.ts

@@ -0,0 +1,73 @@
+/**
+ * @class HistoryAPI
+ * @classdesc Provides public API for history (undo/redo) functionality
+ * @module HistoryAPI
+ */
+import { Module } from '../../__module';
+import type { History as HistoryInterface } from '../../../../types/api';
+
+/**
+ * HistoryAPI provides methods for undo/redo operations
+ */
+export class HistoryAPI extends Module {
+  /**
+   * Available methods for public API
+   */
+  public get methods(): HistoryInterface {
+    return {
+      undo: (): Promise<boolean> => this.undo(),
+      redo: (): Promise<boolean> => this.redo(),
+      canUndo: (): boolean => this.canUndo(),
+      canRedo: (): boolean => this.canRedo(),
+      clear: (): void => this.clear(),
+      captureInitialState: (): Promise<void> => this.captureInitialState(),
+    };
+  }
+
+  /**
+   * Performs undo operation
+   * @returns Promise resolving to true if undo was performed
+   */
+  private async undo(): Promise<boolean> {
+    return this.Blok.History.undo();
+  }
+
+  /**
+   * Performs redo operation
+   * @returns Promise resolving to true if redo was performed
+   */
+  private async redo(): Promise<boolean> {
+    return this.Blok.History.redo();
+  }
+
+  /**
+   * Checks if undo is available
+   * @returns true if there are states to undo
+   */
+  private canUndo(): boolean {
+    return this.Blok.History.canUndo();
+  }
+
+  /**
+   * Checks if redo is available
+   * @returns true if there are states to redo
+   */
+  private canRedo(): boolean {
+    return this.Blok.History.canRedo();
+  }
+
+  /**
+   * Clears the history stacks
+   */
+  private clear(): void {
+    this.Blok.History.clear();
+  }
+
+  /**
+   * Captures the initial document state
+   * @returns Promise that resolves when initial state is captured
+   */
+  private async captureInitialState(): Promise<void> {
+    return this.Blok.History.captureInitialState();
+  }
+}

package/src/components/modules/api/i18n.ts

@@ -0,0 +1,35 @@
+import type { I18n } from '../../../../types/api';
+import { Module } from '../../__module';
+
+/**
+ * API module exposing i18n methods to tools.
+ *
+ * This module follows the standard API module pattern (extend Module, expose `methods` getter).
+ * It provides a stable interface for tools while the internal I18n module can evolve.
+ *
+ * Tools should use full translation keys (e.g., 'tools.link.addLink', 'blockSettings.delete').
+ */
+export class I18nAPI extends Module {
+  /**
+   * Cached methods object to avoid creating new closures on every access.
+   */
+  private cachedMethods: I18n | null = null;
+
+  /**
+   * Returns the I18n API methods for tools.
+   *
+   * The methods object is cached to avoid allocating new closures on each property access,
+   * which would happen frequently as tools call api.i18n.t() during rendering.
+   */
+  public get methods(): I18n {
+    if (this.cachedMethods === null) {
+      this.cachedMethods = {
+        t: (dictKey: string): string => this.Blok.I18n.t(dictKey),
+        has: (dictKey: string): boolean => this.Blok.I18n.has(dictKey),
+        getEnglishTranslation: (key: string): string => this.Blok.I18n.getEnglishTranslation(key),
+      };
+    }
+
+    return this.cachedMethods;
+  }
+}

package/src/components/modules/api/index.ts

@@ -0,0 +1,39 @@
+/**
+ * @module API
+ * @copyright <CodeX> 2018
+ *
+ * Each block has a Blok API instance to use provided public methods
+ * if you cant to read more about how API works, please see docs
+ */
+import { Module } from '../../__module';
+import type { API as APIInterfaces } from '../../../../types';
+
+/**
+ * @class API
+ */
+export class API extends Module {
+  /**
+   * Blok Core API modules
+   */
+  public get methods(): APIInterfaces {
+    return {
+      blocks: this.Blok.BlocksAPI.methods,
+      caret: this.Blok.CaretAPI.methods,
+      tools: this.Blok.ToolsAPI.methods,
+      events: this.Blok.EventsAPI.methods,
+      history: this.Blok.HistoryAPI.methods,
+      listeners: this.Blok.ListenersAPI.methods,
+      notifier: this.Blok.NotifierAPI.methods,
+      sanitizer: this.Blok.SanitizerAPI.methods,
+      saver: this.Blok.SaverAPI.methods,
+      selection: this.Blok.SelectionAPI.methods,
+      styles: this.Blok.StylesAPI.classes,
+      toolbar: this.Blok.ToolbarAPI.methods,
+      inlineToolbar: this.Blok.InlineToolbarAPI.methods,
+      tooltip: this.Blok.TooltipAPI.methods,
+      i18n: this.Blok.I18nAPI.methods,
+      readOnly: this.Blok.ReadOnlyAPI.methods,
+      ui: this.Blok.UiAPI.methods,
+    };
+  }
+}