@jackuait/blok 0.1.1

package/types/index.d.ts

@@ -0,0 +1,191 @@
+/**
+ * For export type there should be one entry point,
+ * so we export all types from this file
+ * ------------------------------------
+ */
+
+import {
+  Dictionary,
+  DictValue,
+  EditorConfig,
+  I18nConfig,
+  I18nDictionary,
+} from './configs';
+
+import {
+  Blocks,
+  Caret,
+  Events,
+  InlineToolbar,
+  Listeners,
+  Notifier,
+  ReadOnly,
+  Sanitizer,
+  Saver,
+  Selection,
+  Styles,
+  Toolbar,
+  Tooltip,
+  I18n,
+  Ui,
+  Tools,
+} from './api';
+
+import { OutputData } from './data-formats';
+import { BlockMutationEvent, BlockMutationEventMap, BlockMutationType } from './events/block';
+import { BlockAddedMutationType, BlockAddedEvent } from './events/block/BlockAdded';
+import { BlockChangedMutationType, BlockChangedEvent } from './events/block/BlockChanged';
+import { BlockMovedMutationType, BlockMovedEvent } from './events/block/BlockMoved';
+import { BlockRemovedMutationType, BlockRemovedEvent } from './events/block/BlockRemoved';
+
+/**
+ * Interfaces used for development
+ */
+export {
+  BaseTool,
+  BaseToolConstructable,
+  InlineTool,
+  InlineToolConstructable,
+  InlineToolConstructorOptions,
+  BlockToolConstructable,
+  BlockToolConstructorOptions,
+  BlockTool,
+  BlockToolData,
+  Tool,
+  ToolConstructable,
+  ToolboxConfig,
+  ToolboxConfigEntry,
+  ToolSettings,
+  ToolConfig,
+  PasteEvent,
+  PasteEventDetail,
+  PatternPasteEvent,
+  PatternPasteEventDetail,
+  HTMLPasteEvent,
+  HTMLPasteEventDetail,
+  FilePasteEvent,
+  FilePasteEventDetail,
+} from './tools';
+export {BlockTune, BlockTuneConstructable} from './block-tunes';
+export {
+  EditorConfig,
+  SanitizerConfig,
+  SanitizerRule,
+  PasteConfig,
+  LogLevels,
+  ConversionConfig,
+  I18nDictionary,
+  Dictionary,
+  DictValue,
+  I18nConfig,
+} from './configs';
+
+export * from './utils/popover';
+
+export { OutputData, OutputBlockData} from './data-formats/output-data';
+export { BlockId } from './data-formats/block-id';
+export { BlockAPI } from './api'
+export {
+  BlockMutationType,
+  BlockMutationEvent,
+  BlockMutationEventMap,
+  BlockAddedMutationType,
+  BlockAddedEvent,
+  BlockRemovedMutationType,
+  BlockRemovedEvent,
+  BlockMovedMutationType,
+  BlockMovedEvent,
+  BlockChangedMutationType,
+  BlockChangedEvent,
+}
+
+/**
+ * We have a namespace API {@link ./api/index.d.ts} (APIMethods) but we can not use it as interface
+ * So we should create new interface for exporting API type
+ */
+export interface API {
+  blocks: Blocks;
+  caret: Caret;
+  tools: Tools;
+  events: Events;
+  listeners: Listeners;
+  notifier: Notifier;
+  sanitizer: Sanitizer;
+  saver: Saver;
+  selection: Selection;
+  styles: Styles;
+  toolbar: Toolbar;
+  inlineToolbar: InlineToolbar;
+  tooltip: Tooltip;
+  i18n: I18n;
+  readOnly: ReadOnly;
+  ui: Ui;
+}
+
+/**
+ * Main Editor class
+ */
+declare class EditorJS {
+  public static version: string;
+
+  public isReady: Promise<void>;
+
+  public blocks: Blocks;
+  public caret: Caret;
+  public sanitizer: Sanitizer;
+  public saver: Saver;
+  public selection: Selection;
+  public styles: Styles;
+  public toolbar: Toolbar;
+  public inlineToolbar: InlineToolbar;
+  public tooltip: Tooltip;
+  public readOnly: ReadOnly;
+  constructor(configuration?: EditorConfig|string);
+
+  /**
+   * API shorthands
+   */
+
+  /**
+   * @see Saver.save
+   */
+  public save(): Promise<OutputData>;
+
+  /**
+   * @see Blocks.clear
+   */
+  public clear(): void;
+
+  /**
+   * @see Blocks.render
+   */
+  public render(data: OutputData): Promise<void>;
+
+  /**
+   * @see Caret.focus
+   */
+  public focus(atEnd?: boolean): boolean;
+
+  /**
+   * @see Events.on
+   */
+  public on(eventName: string, callback: (data?: any) => void): void;
+
+  /**
+   * @see Events.off
+   */
+  public off(eventName: string, callback: (data?: any) => void): void;
+
+  /**
+   * @see Events.emit
+   */
+  public emit(eventName: string, data: any): void;
+
+  /**
+   * Destroy Editor instance and related DOM elements
+   */
+  public destroy(): void;
+}
+
+export as namespace EditorJS;
+export default EditorJS;

package/types/tools/adapters/base-tool-adapter.d.ts

@@ -0,0 +1,76 @@
+import { Tool, ToolSettings } from '..';
+import type { SanitizerConfig } from '../..';
+
+import { ToolType } from './tool-type';
+import { InlineToolAdapter } from './inline-tool-adapter';
+import { BlockToolAdapter } from './block-tool-adapter';
+import { BlockTuneAdapter } from './block-tune-adapter';
+
+export interface BaseToolAdapter<Type extends ToolType, ToolClass extends Tool> {
+  /**
+   * Tool type: Block, Inline or Tune
+   */
+  type: Type;
+
+  /**
+   * Tool name specified in EditorJS config
+   */
+  name: string;
+
+  /**
+   * Flag show is current Tool internal (bundled with EditorJS core) or not
+   */
+  readonly isInternal: boolean;
+
+  /**
+   * Flag show is current Tool default or not
+   */
+  readonly isDefault: boolean;
+
+  /**
+   * Returns Tool user configuration
+   */
+  settings: ToolSettings;
+
+  /**
+   * Calls Tool's reset method
+   */
+  reset(): void | Promise<void>;
+
+  /**
+   * Calls Tool's prepare method
+   */
+  prepare(): void | Promise<void>;
+
+  /**
+   * Returns shortcut for Tool (internal or specified by user)
+   */
+  shortcut: string | undefined;
+
+  /**
+   * Returns Tool's sanitizer configuration
+   */
+  sanitizeConfig: SanitizerConfig;
+
+  /**
+   * Returns true if Tools is inline
+   */
+  isInline(): this is InlineToolAdapter;
+
+  /**
+   * Returns true if Tools is block
+   */
+  isBlock(): this is BlockToolAdapter;
+
+  /**
+   * Returns true if Tools is tune
+   */
+  isTune(): this is BlockTuneAdapter;
+
+  /**
+   * Constructs new Tool instance from constructable blueprint
+   *
+   * @param args
+   */
+  create(...args: any[]): ToolClass;
+}

package/types/tools/adapters/block-tool-adapter.d.ts

@@ -0,0 +1,78 @@
+import { ToolsCollection } from './tools-collection';
+import { ToolType } from './tool-type';
+import { InlineToolAdapter } from './inline-tool-adapter';
+import { BlockTuneAdapter } from './block-tune-adapter';
+import { BlockTool } from '../block-tool';
+import { BlockToolData } from '../block-tool-data';
+import { BlockAPI } from '../../api/block';
+import { ToolboxConfigEntry } from '../tool-settings';
+import { ConversionConfig } from '../../configs/conversion-config';
+import { PasteConfig } from '../../configs/paste-config';
+import { SanitizerConfig } from '../../configs/sanitizer-config';
+import { BaseToolAdapter } from './base-tool-adapter';
+
+interface BlockToolAdapter extends BaseToolAdapter<ToolType.Block, BlockTool>{
+  /**
+   * InlineTool collection for current Block Tool
+   */
+  inlineTools: ToolsCollection<InlineToolAdapter>;
+
+  /**
+   * BlockTune collection for current Block Tool
+   */
+  tunes: ToolsCollection<BlockTuneAdapter>;
+
+  /**
+   * Creates new Tool instance
+   * @param data - Tool data
+   * @param block - BlockAPI for current Block
+   * @param readOnly - True if Editor is in read-only mode
+   */
+  create(data: BlockToolData, block: BlockAPI, readOnly: boolean): BlockTool;
+
+  /**
+   * Returns true if read-only mode is supported by Tool
+   */
+  isReadOnlySupported: boolean;
+
+  /**
+   * Returns true if Tool supports linebreaks
+   */
+  isLineBreaksEnabled: boolean;
+
+  /**
+   * Returns Tool toolbox configuration (internal or user-specified)
+   */
+  toolbox: ToolboxConfigEntry[] | undefined;
+
+  /**
+   * Returns Tool conversion configuration
+   */
+  conversionConfig: ConversionConfig | undefined;
+
+  /**
+   * Returns enabled inline tools for Tool
+   */
+  enabledInlineTools: boolean | string[];
+
+  /**
+   * Returns enabled tunes for Tool
+   */
+  enabledBlockTunes: boolean | string[] | undefined;
+
+  /**
+   * Returns Tool paste configuration
+   */
+  pasteConfig: PasteConfig;
+
+  /**
+   * Returns sanitize configuration for Block Tool including configs from related Inline Tools and Block Tunes
+   */
+  sanitizeConfig: SanitizerConfig;
+
+  /**
+   * Returns sanitizer configuration composed from sanitize config of Inline Tools enabled for Tool
+   */
+  baseSanitizeConfig: SanitizerConfig;
+}
+

package/types/tools/adapters/block-tune-adapter.d.ts

@@ -0,0 +1,14 @@
+import { BlockAPI, BlockTune } from '../..';
+import { BlockTuneData } from '../../block-tunes/block-tune-data';
+import { BaseToolAdapter } from './base-tool-adapter';
+import { ToolType } from './tool-type';
+
+interface BlockTuneAdapter extends BaseToolAdapter<ToolType.Tune, BlockTune> {
+  /**
+   * Constructs new BlockTune instance from constructable
+   *
+   * @param data - Tune data
+   * @param block - Block API object
+   */
+  create(data: BlockTuneData, block: BlockAPI): BlockTune;
+}

package/types/tools/adapters/inline-tool-adapter.d.ts

@@ -0,0 +1,10 @@
+import { InlineTool as IInlineTool, InlineTool } from '../..';
+import { BaseToolAdapter } from './base-tool-adapter';
+import { ToolType } from './tool-type';
+
+interface InlineToolAdapter extends BaseToolAdapter<ToolType.Inline, InlineTool> {
+  /**
+   * Constructs new InlineTool instance from constructable
+   */
+  create(): IInlineTool;
+}

package/types/tools/adapters/tool-factory.d.ts

@@ -0,0 +1,5 @@
+import { BlockToolAdapter } from './block-tool-adapter';
+import { BlockTuneAdapter } from './block-tune-adapter';
+import { InlineToolAdapter } from './inline-tool-adapter';
+
+export type ToolFactory = BlockToolAdapter | InlineToolAdapter | BlockTuneAdapter;

package/types/tools/adapters/tool-type.ts

@@ -0,0 +1,18 @@
+/**
+ * What kind of plugins developers can create
+ */
+export enum ToolType {
+  /**
+   * Block tool
+   */
+  Block,
+  /**
+   * Inline tool
+   */
+  Inline,
+
+  /**
+   * Block tune
+   */
+  Tune,
+}

package/types/tools/adapters/tools-collection.d.ts

@@ -0,0 +1,34 @@
+import { BlockToolAdapter } from './block-tool-adapter';
+import { BlockTuneAdapter } from './block-tune-adapter';
+import { InlineToolAdapter } from './inline-tool-adapter';
+import { ToolFactory } from './tool-factory';
+
+/**
+ * Interface for a collection of tools.
+ */
+export interface ToolsCollection<V extends ToolFactory = ToolFactory> {
+  /**
+   * Returns Block Tools collection
+   */
+  blockTools: ToolsCollection<BlockToolAdapter>;
+
+  /**
+   * Returns Inline Tools collection
+   */
+  inlineTools: ToolsCollection<InlineToolAdapter>;
+
+  /**
+   * Returns Block Tunes collection
+   */
+  blockTunes: ToolsCollection<BlockTuneAdapter>;
+
+  /**
+   * Returns internal Tools collection
+   */
+  internalTools: ToolsCollection<V>;
+
+  /**
+   * Returns Tools collection provided by user
+   */
+  externalTools: ToolsCollection<V>;
+}

package/types/tools/block-tool-data.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Object returned by Tool's {@link BlockTool#save} method
+ * Specified by Tool developer, so leave it as object
+ */
+export type BlockToolData<T extends object = any> = T;

package/types/tools/block-tool.d.ts

@@ -0,0 +1,121 @@
+import { ConversionConfig, PasteConfig, SanitizerConfig } from '../configs';
+import { BlockToolData } from './block-tool-data';
+import { BaseTool, BaseToolConstructable, BaseToolConstructorOptions } from './tool';
+import { ToolConfig } from './tool-config';
+import { API, BlockAPI, ToolboxConfig } from '../index';
+import { PasteEvent } from './paste-events';
+import { MoveEvent } from './hook-events';
+import { MenuConfig } from './menu-config';
+
+/**
+ * Describe Block Tool object
+ * @see {@link docs/tools.md}
+ */
+export interface BlockTool extends BaseTool {
+  /**
+   * Sanitizer rules description
+   */
+  sanitize?: SanitizerConfig;
+
+  /**
+   * Process Tool's element in DOM and return raw data
+   * @param {HTMLElement} block - element created by {@link BlockTool#render} function
+   * @return {BlockToolData}
+   */
+  save(block: HTMLElement): BlockToolData;
+
+  /**
+   * Create Block's settings block
+   */
+  renderSettings?(): HTMLElement | MenuConfig;
+
+  /**
+   * Validate Block's data
+   * @param {BlockToolData} blockData
+   * @return {boolean}
+   */
+  validate?(blockData: BlockToolData): boolean;
+
+  /**
+   * Method that specified how to merge two Blocks with same type.
+   * Called by backspace at the beginning of the Block
+   * @param {BlockToolData} blockData
+   */
+  merge?(blockData: BlockToolData): void;
+
+  /**
+   * On paste callback. Fired when pasted content can be substituted by a Tool
+   * @param {PasteEvent} event
+   */
+  onPaste?(event: PasteEvent): void;
+
+  /**
+   * Cleanup resources used by your tool here
+   * Called when the editor is destroyed
+   */
+  destroy?(): void;
+
+  /**
+   * Lifecycle hooks
+   */
+
+  /**
+   * Called after block content added to the page
+   */
+  rendered?(): void;
+
+  /**
+   * Called each time block content is updated
+   */
+  updated?(): void;
+
+  /**
+   * Called after block removed from the page but before instance is deleted
+   */
+  removed?(): void;
+
+  /**
+   * Called after block was moved
+   */
+  moved?(event: MoveEvent): void;
+}
+
+/**
+ * Describe constructor parameters
+ */
+export interface BlockToolConstructorOptions<D extends object = any, C extends object = any> extends BaseToolConstructorOptions<C> {
+  data: BlockToolData<D>;
+  block: BlockAPI;
+  readOnly: boolean;
+}
+
+export interface BlockToolConstructable extends BaseToolConstructable {
+  /**
+   * Tool's Toolbox settings
+   */
+  toolbox?: ToolboxConfig;
+
+  /**
+   * Paste substitutions configuration
+   */
+  pasteConfig?: PasteConfig | false;
+
+  /**
+   * Rules that specified how this Tool can be converted into/from another Tool
+   */
+  conversionConfig?: ConversionConfig;
+
+  /**
+   * Is Tool supports read-only mode, this property should return true
+   */
+  isReadOnlySupported?: boolean;
+
+  /**
+   * @constructor
+   *
+   * @param {BlockToolConstructorOptions} config - constructor parameters
+   *
+   * @return {BlockTool}
+   */
+  new(config: BlockToolConstructorOptions): BlockTool;
+}

package/types/tools/hook-events.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Event detail for block relocation
+ */
+export interface MoveEventDetail {
+  /**
+   * index the block was moved from
+   */
+  fromIndex: number;
+  /**
+   * index the block was moved to
+   */
+  toIndex: number;
+}
+
+/**
+ * Move event for block relocation
+ */
+export interface MoveEvent extends CustomEvent {
+  /**
+   * Override detail property of CustomEvent by MoveEvent hook
+   */
+  readonly detail: MoveEventDetail;
+}

package/types/tools/index.d.ts

@@ -0,0 +1,16 @@
+import { BlockTool, BlockToolConstructable } from './block-tool';
+import { InlineTool, InlineToolConstructable } from './inline-tool';
+import { BlockTune, BlockTuneConstructable } from '../block-tunes';
+
+export * from './block-tool';
+export * from './block-tool-data';
+export * from './inline-tool';
+export * from './tool';
+export * from './tool-config';
+export * from './tool-settings';
+export * from './paste-events';
+export * from './hook-events';
+export * from './menu-config';
+
+export type Tool = BlockTool | InlineTool | BlockTune;
+export type ToolConstructable = BlockToolConstructable | InlineToolConstructable | BlockTuneConstructable;

package/types/tools/inline-tool.d.ts

@@ -0,0 +1,37 @@
+import {BaseTool, BaseToolConstructable} from './tool';
+import {API, ToolConfig} from '../index';
+import { MenuConfig } from './menu-config';
+/**
+ * Base structure for the Inline Toolbar Tool
+ */
+export interface InlineTool extends BaseTool<MenuConfig> {
+  /**
+   * Shortcut for Tool
+   * @type {string}
+   */
+  shortcut?: string;
+}
+
+
+/**
+ * Describe constructor parameters
+ */
+export interface InlineToolConstructorOptions {
+  api: API;
+  config?: ToolConfig;
+}
+
+export interface InlineToolConstructable extends BaseToolConstructable {
+  /**
+   * Constructor
+   *
+   * @param {InlineToolConstructorOptions} config - constructor parameters
+   */
+  new(config: InlineToolConstructorOptions): InlineTool;
+
+  /**
+   * Allows inline tool to be available in read-only mode
+   * Can be used, for example, by comments tool
+   */
+  isReadOnlySupported?: boolean;
+}

package/types/tools/menu-config.d.ts

@@ -0,0 +1,46 @@
+import { PopoverItemDefaultBaseParams, PopoverItemHtmlParams, PopoverItemSeparatorParams, WithChildren } from '../utils/popover';
+
+/**
+ * Menu configuration format.
+ * Is used for defining Block Tunes Menu items via Block Tool's renderSettings(), Block Tune's render() and Inline Tool's render().
+ */
+export type MenuConfig = MenuConfigItem | MenuConfigItem[];
+
+/**
+ * Common parameters for all kinds of default Menu Config items: with or without confirmation
+ */
+type MenuConfigDefaultBaseParams = PopoverItemDefaultBaseParams;
+
+/**
+ * Menu Config item with confirmation
+ */
+type MenuConfigItemDefaultWithConfirmationParams = Omit<MenuConfigDefaultBaseParams, 'onActivate'> & {
+  /**
+   * Items with confirmation should not have onActivate handler
+   */
+  onActivate?: never;
+
+  /**
+   * Menu Config item parameters that should be applied on item activation.
+   * May be used to ask user for confirmation before executing item activation handler.
+   */
+  confirmation: MenuConfigDefaultBaseParams;
+
+}
+
+/**
+ * Default, non-separator and non-html Menu Config items type
+ */
+type MenuConfigItemDefaultParams =
+  MenuConfigItemDefaultWithConfirmationParams |
+  MenuConfigDefaultBaseParams |
+  WithChildren<MenuConfigDefaultBaseParams>;
+
+/**
+ * Single Menu Config item
+ */
+type MenuConfigItem =
+  MenuConfigItemDefaultParams |
+  PopoverItemSeparatorParams |
+  PopoverItemHtmlParams |
+  WithChildren<PopoverItemHtmlParams>;