@jackuait/blok 0.1.1

package/types/block-tunes/block-tune.d.ts

@@ -0,0 +1,60 @@
+import {API, BlockAPI, ToolConfig} from '../index';
+import { BlockTuneData } from './block-tune-data';
+import { BaseToolConstructable, MenuConfig } from '../tools';
+
+/**
+ * Describes BLockTune blueprint
+ */
+export interface BlockTune {
+  /**
+   * Returns BlockTune's UI.
+   * Should return either MenuConfig (recommended) (@see https://editorjs.io/menu-config/)
+   * or an HTMLElement (UI consistency is not guaranteed)
+   */
+  render(): HTMLElement | MenuConfig;
+
+  /**
+   * Method called on Tool render. Pass Tool content as an argument.
+   *
+   * You can wrap Tool's content with any wrapper you want to provide Tune's UI
+   *
+   * @param {HTMLElement} pluginsContent — Tool's content wrapper
+   */
+  wrap?(pluginsContent: HTMLElement): HTMLElement;
+
+  /**
+   * Called on Tool's saving. Should return any data Tune needs to save
+   *
+   * @return {BlockTuneData}
+   */
+  save?(): BlockTuneData;
+}
+
+/**
+ * Describes BlockTune class constructor function
+ */
+export interface BlockTuneConstructable extends BaseToolConstructable {
+
+  /**
+   * Flag show Tool is Block Tune
+   */
+  isTune: boolean;
+
+  /**
+   * @constructor
+   *
+   * @param config - Block Tune config
+   */
+  new(config: {
+    api: API,
+    config?: ToolConfig,
+    block: BlockAPI,
+    data: BlockTuneData,
+  }): BlockTune;
+
+  /**
+   * Tune`s prepare method. Can be async
+   * @param data
+   */
+  prepare?(data: { toolName: string; config: ToolConfig }): Promise<void> | void;
+}

package/types/block-tunes/index.d.ts

@@ -0,0 +1 @@
+export * from './block-tune';

package/types/configs/conversion-config.ts

@@ -0,0 +1,26 @@
+import type { BlockToolData, ToolConfig } from '../tools';
+
+/**
+ * Config allows Tool to specify how it can be converted into/from another Tool
+ */
+export interface ConversionConfig {
+  /**
+   * How to import string to this Tool.
+   *
+   * Can be a String or Function:
+   *
+   * 1. String — the key of Tool data object to fill it with imported string on render.
+   * 2. Function — method that accepts importing string and composes Tool data to render.
+   */
+  import?: ((data: string, config: ToolConfig) => BlockToolData) | string;
+
+  /**
+   * How to export this Tool to make other Block.
+   *
+   * Can be a String or Function:
+   *
+   * 1. String — which property of saved Tool data should be used as exported string.
+   * 2. Function — accepts saved Tool data and create a string to export
+   */
+  export?: ((data: BlockToolData) => string) | string;
+}

package/types/configs/editor-config.d.ts

@@ -0,0 +1,107 @@
+import {ToolConstructable, ToolSettings} from '../tools';
+import {API, LogLevels, OutputData} from '../index';
+import {SanitizerConfig} from './sanitizer-config';
+import {I18nConfig} from './i18n-config';
+import { BlockMutationEvent } from '../events/block';
+
+export interface EditorConfig {
+  /**
+   * Element where Editor will be appended
+   */
+  holder?: string | HTMLElement;
+
+  /**
+   * If true, set caret at the first Block after Editor is ready
+   */
+  autofocus?: boolean;
+
+  /**
+   * This Tool will be used as default
+   * Name should be equal to one of Tool`s keys of passed tools
+   * If not specified, Paragraph Tool will be used
+   */
+  defaultBlock?: string;
+
+
+
+  /**
+   * First Block placeholder
+   */
+  placeholder?: string|false;
+
+  /**
+   * Define default sanitizer configuration
+   * @see {@link sanitizer}
+   */
+  sanitizer?: SanitizerConfig;
+
+  /**
+   * If true, toolbar won't be shown
+   */
+  hideToolbar?: boolean;
+
+  /**
+   * Map of Tools to use
+   */
+  tools?: {
+    [toolName: string]: ToolConstructable|ToolSettings;
+  }
+
+  /**
+   * Data to render on Editor start
+   */
+  data?: OutputData;
+
+  /**
+   * Height of Editor's bottom area that allows to set focus on the last Block
+   */
+  minHeight?: number;
+
+  /**
+   * Editors log level (how many logs you want to see)
+   */
+  logLevel?: LogLevels;
+
+  /**
+   * Enable read-only mode
+   */
+  readOnly?: boolean;
+
+  /**
+   * Internalization config
+   */
+  i18n?: I18nConfig;
+
+  /**
+   * Fires when Editor is ready to work
+   */
+  onReady?(): void;
+
+  /**
+   * Fires when something changed in DOM
+   * @param api - editor.js api
+   * @param event - custom event describing mutation. If several mutations happened at once, they will be batched and you'll get an array of events here.
+   */
+  onChange?(api: API, event: BlockMutationEvent | BlockMutationEvent[]): void;
+
+  /**
+   * Defines default toolbar for all tools.
+   */
+  inlineToolbar?: string[]|boolean;
+
+  /**
+   * Common Block Tunes list. Will be added to all the blocks which do not specify their own 'tunes' set
+   */
+  tunes?: string[];
+
+  /**
+   * Section for style-related settings
+   */
+  style?: {
+    /**
+     * A random value to handle Content Security Policy "style-src" policy
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce
+     */
+    nonce?: string;
+  }
+}

package/types/configs/i18n-config.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Available options of i18n config property
+ */
+import { I18nDictionary } from './i18n-dictionary';
+
+export interface I18nConfig {
+  /**
+   * Dictionary used for translation
+   */
+  messages?: I18nDictionary;
+
+  /**
+   * Text direction. If not set, uses ltr
+   */
+  direction?: 'ltr' | 'rtl';
+}

package/types/configs/i18n-dictionary.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Structure of the i18n dictionary
+ */
+export interface I18nDictionary {
+  /**
+   * Section for translation Tool Names: both block and inline tools
+   * Example:
+   *  "toolNames": {
+   *     "Text": "Параграф",
+   *     "Heading": "Заголовок",
+   *     "List": "Список",
+   *     ...
+   *  },
+   */
+  toolNames?: Dictionary;
+
+  /**
+   * Section for passing translations to the external tools classes
+   * The first-level keys of this object should be equal of keys ot the 'tools' property of EditorConfig
+   * Includes internal tools: "paragraph", "stub"
+   *
+   * Example:
+   *  "tools": {
+   *     "warning": {
+   *       "Title": "Название",
+   *       "Message": "Сообщение",
+   *     },
+   *     "link": {
+   *        "Add a link": "Вставьте ссылку"
+   *     },
+   *  },
+   */
+  tools?: Dictionary;
+
+  /**
+   * Section allows to translate Block Tunes
+   * The first-level keys of this object should be equal of 'name' ot the 'tools.<toolName>.tunes' property of EditorConfig
+   * Including some internal block-tunes: "delete", "moveUp", "moveDown
+   *
+   * Example:
+   * "blockTunes": {
+   *   "delete": {
+   *     "Delete": "Удалить"
+   *   },
+   *   "moveUp": {
+   *     "Move up": "Переместить вверх"
+   *   },
+   *   "moveDown": {
+   *     "Move down": "Переместить вниз"
+   *   }
+   * },
+   */
+  blockTunes?: Dictionary;
+
+  /**
+   * Translation of internal UI components of the editor.js core
+   */
+  ui?: Dictionary;
+}
+
+/**
+ * Represent item of the I18nDictionary config
+ */
+export interface Dictionary {
+  /**
+   * The keys of the object can represent two entities:
+   *  1. Dictionary key usually is an original string from default locale, like "Convert to"
+   *  2. Sub-namespace section, like "toolbar.converter.<...>"
+   *
+   *  Example of 1:
+   *  toolbox: {
+   *    "Add": "Добавить",
+   *  }
+   *
+   *  Example of 2:
+   *  ui: {
+   *    toolbar: {
+   *      toolbox: {    <-- Example of 1
+   *        "Add": "Добавить"
+   *      }
+   *    }
+   *  }
+   */
+  [key: string]: DictValue;
+}
+
+/**
+ * The value of the dictionary can be:
+ *  - other dictionary
+ *  - result translate string
+ */
+export type DictValue = {[key: string]: Dictionary | string} | string;
+

package/types/configs/index.d.ts

@@ -0,0 +1,7 @@
+export * from './editor-config';
+export * from './sanitizer-config';
+export * from './paste-config';
+export * from './conversion-config';
+export * from './log-levels';
+export * from './i18n-config';
+export * from './i18n-dictionary';

package/types/configs/log-levels.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Available log levels
+ */
+export enum LogLevels {
+  VERBOSE = 'VERBOSE',
+  INFO = 'INFO',
+  WARN = 'WARN',
+  ERROR = 'ERROR',
+}

package/types/configs/paste-config.d.ts

@@ -0,0 +1,38 @@
+import { SanitizerConfig } from './sanitizer-config';
+
+/**
+ * Tool onPaste configuration object
+ */
+interface PasteConfigSpecified {
+  /**
+   * Array of tags Tool can substitute.
+   *
+   * Could also contain a sanitize-config if you need to save some tag's attribute.
+   * For example:
+   * [
+   *   {
+   *     img: { src: true },
+   *   }
+   * ],
+   * @type string[]
+   */
+  tags?: (string | SanitizerConfig)[];
+
+  /**
+   * Object of string patterns Tool can substitute.
+   * Key is your internal key and value is RegExp
+   *
+   * @type {{[key: string]: RegExp}}
+   */
+  patterns?: {[key: string]: RegExp};
+
+  /**
+   * Object with arrays of extensions and MIME types Tool can substitute
+   */
+  files?: {extensions?: string[], mimeTypes?: string[]};
+}
+
+/**
+ * Alias for PasteConfig with false
+ */
+export type PasteConfig = PasteConfigSpecified | false;

package/types/configs/sanitizer-config.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Sanitizer config of each HTML element
+ * @see {@link https://github.com/guardian/html-janitor#options}
+ */
+export type TagConfig = boolean | { [attr: string]: boolean | string };
+
+export type SanitizerRule = TagConfig | ((el: Element) => TagConfig)
+
+export interface SanitizerConfig {
+  /**
+   * Tag name and params not to be stripped off
+   * @see {@link https://github.com/guardian/html-janitor}
+   *
+   * @example Save P tags
+   * p: true
+   *
+   * @example Save A tags and do not strip HREF attribute
+   * a: {
+   *   href: true
+   * }
+   *
+   * @example Save A tags with TARGET="_blank" attribute
+   * a: function (aTag) {
+   *   return aTag.target === '_black';
+   * }
+   *
+   * @example Save U tags that are not empty
+   * u: function(el){
+   *   return el.textContent !== '';
+   * }
+   *
+   * @example For blockquote with class 'indent' save CLASS and STYLE attributes
+   *          Otherwise strip all attributes
+   * blockquote: function(el) {
+   *   if (el.classList.contains('indent')) {
+   *     return { 'class': true, 'style': true };
+   *   } else {
+   *     return {};
+   *   }
+   * }
+   */
+  [key: string]: SanitizerRule;
+}

package/types/data-formats/block-data.d.ts

@@ -0,0 +1,23 @@
+import {BlockToolData} from '../tools';
+import { BlockId } from './block-id';
+
+/**
+ * Tool's saved data
+ */
+export interface SavedData {
+  id: BlockId;
+  tool: string;
+  data: BlockToolData;
+  time: number;
+}
+
+/**
+ * Tool's data after validation
+ */
+export interface ValidatedData {
+  id?: BlockId;
+  tool?: string;
+  data?: BlockToolData;
+  time?: number;
+  isValid: boolean;
+}

package/types/data-formats/block-id.ts

@@ -0,0 +1,4 @@
+/**
+ * Unique identifier of a block
+ */
+export type BlockId = string;

package/types/data-formats/index.d.ts

@@ -0,0 +1,2 @@
+export * from './block-data';
+export * from './output-data';

package/types/data-formats/output-data.d.ts

@@ -0,0 +1,46 @@
+import {BlockToolData} from '../tools';
+import {BlockTuneData} from '../block-tunes/block-tune-data';
+import { BlockId } from './block-id';
+
+/**
+ * Output of one Tool
+ *
+ * @template Type - the string literal describing a tool type
+ * @template Data - the structure describing a data object supported by the tool
+ */
+export interface OutputBlockData<Type extends string = string, Data extends object = any> {
+  /**
+   * Unique Id of the block
+   */
+  id?: BlockId;
+  /**
+   * Tool type
+   */
+  type: Type;
+  /**
+   * Saved Block data
+   */
+  data: BlockToolData<Data>;
+
+  /**
+   * Block Tunes data
+   */
+  tunes?: {[name: string]: BlockTuneData};
+}
+
+export interface OutputData {
+  /**
+   * Editor's version
+   */
+  version?: string;
+
+  /**
+   * Timestamp of saving in milliseconds
+   */
+  time?: number;
+
+  /**
+   * Saved Blocks
+   */
+  blocks: OutputBlockData[];
+}

package/types/events/block/Base.ts

@@ -0,0 +1,11 @@
+import type { BlockAPI } from '../../api';
+
+/**
+ * Details of CustomEvent fired on block mutation
+ */
+export interface BlockMutationEventDetail {
+  /**
+   * Affected block
+   */
+  target: BlockAPI;
+}

package/types/events/block/BlockAdded.ts

@@ -0,0 +1,21 @@
+import type { BlockMutationEventDetail } from './Base';
+
+/**
+ * Type name of CustomEvent related to block added event
+ */
+export const BlockAddedMutationType = 'block-added';
+
+/**
+ * Information about added block
+ */
+interface BlockAddedEventDetail extends BlockMutationEventDetail {
+  /**
+   * Index of added block
+   */
+  index: number;
+}
+
+/**
+ * Event will be fired when the new block is added to the editor
+ */
+export type BlockAddedEvent = CustomEvent<BlockAddedEventDetail>;

package/types/events/block/BlockChanged.ts

@@ -0,0 +1,21 @@
+import type { BlockMutationEventDetail } from './Base';
+
+/**
+ * Type name of CustomEvent related to block changed event
+ */
+export const BlockChangedMutationType = 'block-changed';
+
+/**
+ * Information about changed block
+ */
+interface BlockChangedEventDetail extends BlockMutationEventDetail {
+  /**
+   * Index of changed block
+   */
+  index: number;
+}
+
+/**
+ * Event will be fired when some block is changed
+ */
+export type BlockChangedEvent = CustomEvent<BlockChangedEventDetail>;

package/types/events/block/BlockMoved.ts

@@ -0,0 +1,26 @@
+import type { BlockMutationEventDetail } from './Base';
+
+/**
+ * Type name of CustomEvent related to block moved event
+ */
+export const BlockMovedMutationType = 'block-moved';
+
+/**
+ * Information about moved block
+ */
+interface BlockMovedEventDetail extends BlockMutationEventDetail {
+  /**
+   * Previous block position
+   */
+  fromIndex: number;
+
+  /**
+   * New block position
+   */
+  toIndex: number;
+}
+
+/**
+ * Event will be fired when some block is moved to another position
+ */
+export type BlockMovedEvent = CustomEvent<BlockMovedEventDetail>;

package/types/events/block/BlockRemoved.ts

@@ -0,0 +1,21 @@
+import type { BlockMutationEventDetail } from './Base';
+
+/**
+ * Type name of CustomEvent related to block removed event
+ */
+export const BlockRemovedMutationType = 'block-removed';
+
+/**
+ * Information about removed block
+ */
+interface BlockRemovedEventDetail extends BlockMutationEventDetail {
+  /**
+   * Index of removed block
+   */
+  index: number;
+}
+
+/**
+ * Event will be fired when some block is removed
+ */
+export type BlockRemovedEvent = CustomEvent<BlockRemovedEventDetail>;

package/types/events/block/index.ts

@@ -0,0 +1,44 @@
+import type { BlockAddedEvent, BlockAddedMutationType } from './BlockAdded';
+import type { BlockChangedEvent, BlockChangedMutationType } from './BlockChanged';
+import type { BlockMovedEvent, BlockMovedMutationType } from './BlockMoved';
+import type { BlockRemovedEvent, BlockRemovedMutationType } from './BlockRemoved';
+
+/**
+ * Map for Custom Events related to block mutation types
+ */
+export interface BlockMutationEventMap {
+  /**
+   * New Block added
+   */
+  [BlockAddedMutationType]: BlockAddedEvent;
+
+  /**
+   * On Block deletion
+   */
+  [BlockRemovedMutationType]: BlockRemovedEvent;
+
+  /**
+   * Moving of a Block
+   */
+  [BlockMovedMutationType]: BlockMovedEvent;
+
+  /**
+   * Any changes inside the Block
+   */
+  [BlockChangedMutationType]: BlockChangedEvent;
+}
+
+/**
+ * What kind of modification happened with the Block
+ */
+export type BlockMutationType = keyof BlockMutationEventMap;
+
+/**
+ * Returns a union type of values of passed object
+ */
+type ValueOf<T> = T[keyof T];
+
+/**
+ * CustomEvent describing a change related to a block
+ */
+export type BlockMutationEvent = ValueOf<BlockMutationEventMap>;