@jackuait/blok 0.1.1

package/types/api/block.d.ts

@@ -0,0 +1,87 @@
+import {BlockToolData, ToolConfig, ToolboxConfigEntry} from '../tools';
+import {SavedData} from '../data-formats';
+
+/**
+ * @interface BlockAPI Describes Block API methods and properties
+ */
+export interface BlockAPI {
+  /**
+   * Block unique identifier
+   */
+  readonly id: string;
+
+  /**
+   * Tool name
+   */
+  readonly name: string;
+
+  /**
+   * Tool config passed on Editor's initialization
+   */
+  readonly config: ToolConfig;
+
+  /**
+   * Wrapper of Tool's HTML element
+   */
+  readonly holder: HTMLElement;
+
+  /**
+   * True if Block content is empty
+   */
+  readonly isEmpty: boolean;
+
+  /**
+   * True if Block is selected with Cross-Block selection
+   */
+  readonly selected: boolean;
+
+  /**
+   * True if Block has inputs to be focused
+   */
+  readonly focusable: boolean;
+
+  /**
+   * Setter sets Block's stretch state
+   *
+   * Getter returns true if Block is stretched
+   */
+  stretched: boolean;
+
+  /**
+   * Call Tool method with errors handler under-the-hood
+   *
+   * @param {string} methodName - method to call
+   * @param {object} param - object with parameters
+   *
+   * @return {void}
+   */
+  call(methodName: string, param?: object): void;
+
+  /**
+   * Save Block content
+   *
+   * @return {Promise<void|SavedData>}
+   */
+  save(): Promise<void|SavedData>;
+
+  /**
+   * Validate Block data
+   *
+   * @param {BlockToolData} data
+   *
+   * @return {Promise<boolean>}
+   */
+  validate(data: BlockToolData): Promise<boolean>;
+
+  /**
+   * Allows to say Editor that Block was changed. Used to manually trigger Editor's 'onChange' callback
+   * Can be useful for block changes invisible for editor core.
+   */
+  dispatchChange(): void;
+
+  /**
+   * Tool could specify several entries to be displayed at the Toolbox (for example, "Heading 1", "Heading 2", "Heading 3")
+   * This method returns the entry that is related to the Block (depended on the Block data)
+   */
+  getActiveToolboxEntry(): Promise<ToolboxConfigEntry | undefined>
+}

package/types/api/blocks.d.ts

@@ -0,0 +1,136 @@
+import {OutputBlockData, OutputData} from '../data-formats/output-data';
+import {BlockToolData, ToolConfig} from '../tools';
+import {BlockAPI} from './block';
+import {BlockTuneData} from '../block-tunes/block-tune-data';
+
+/**
+ * Describes methods to manipulate with Editor`s blocks
+ */
+export interface Blocks {
+  /**
+   * Remove all blocks from Editor zone
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Render passed data
+   *
+   * @param {OutputData} data - saved Block data
+   *
+   * @returns {Promise<void>}
+   */
+  render(data: OutputData): Promise<void>;
+
+  /**
+   * Render passed HTML string
+   * @param {string} data
+   * @return {Promise<void>}
+   */
+  renderFromHTML(data: string): Promise<void>;
+
+  /**
+   * Removes current Block
+   * @param {number} index - index of a block to delete
+   */
+  delete(index?: number): void;
+
+  /**
+   * Moves a block to a new index
+   * @param {number} toIndex - index where the block is moved to
+   * @param {number} fromIndex - block to move
+   */
+  move(toIndex: number, fromIndex?: number): void;
+
+  /**
+   * Returns Block API object by passed Block index
+   * @param {number} index
+   */
+  getBlockByIndex(index: number): BlockAPI | undefined;
+
+  /**
+   * Returns Block API object by passed Block id
+   * @param id - id of the block
+   */
+  getById(id: string): BlockAPI | null;
+
+  /**
+   * Returns current Block index
+   * @returns {number}
+   */
+  getCurrentBlockIndex(): number;
+
+  /**
+   * Returns the index of Block by id;
+   */
+  getBlockIndex(blockId: string): number | undefined;
+
+  /**
+   * Get Block API object by html element
+   *
+   * @param element - html element to get Block by
+   */
+  getBlockByElement(element: HTMLElement): BlockAPI | undefined;
+
+  /**
+   * Returns Blocks count
+   * @return {number}
+   */
+  getBlocksCount(): number;
+
+  /**
+   * Insert new Block and return inserted Block 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 {boolean?} replace - should the existed Block on that index be replaced or not
+   * @param {string} id — An optional id for the new block. If omitted then the new id will be generated
+   */
+  insert(
+    type?: string,
+    data?: BlockToolData,
+    config?: ToolConfig,
+    index?: number,
+    needToFocus?: boolean,
+    replace?: boolean,
+    id?: string,
+  ): BlockAPI;
+
+  /**
+   * Inserts several Blocks to specified index
+   */
+  insertMany(
+    blocks: OutputBlockData[],
+    index?: number,
+  ): BlockAPI[];
+
+
+  /**
+   * Creates data of an empty block with a passed type.
+   *
+   * @param toolName - block tool name
+   */
+  composeBlockData(toolName: string): Promise<BlockToolData>
+
+  /**
+   * Updates block data by id
+   *
+   * @param id - id of the block to update
+   * @param data - (optional) the new data. Can be partial.
+   * @param tunes - (optional) tune data
+   */
+  update(id: string, data?: Partial<BlockToolData>, tunes?: {[name: string]: BlockTuneData}): Promise<BlockAPI>;
+
+  /**
+   * Converts block to another type. Both blocks should provide the conversionConfig.
+   *
+   * @param id - id of the existed 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
+   */
+  convert(id: string, newType: string, dataOverrides?: BlockToolData): Promise<BlockAPI>;
+}

package/types/api/caret.d.ts

@@ -0,0 +1,67 @@
+import { BlockAPI } from "./block";
+
+/**
+ * Describes Editor`s caret API
+ */
+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 blockOrIdOrIndex - BlockAPI or Block id or Block index
+   * @param position - position where to set caret
+   * @param offset - caret offset
+   *
+   * @return {boolean}
+   */
+  setToBlock(blockOrIdOrIndex: BlockAPI | BlockAPI['id'] | number, position?: 'end'|'start'|'default', offset?: number): boolean;
+
+  /**
+   * Sets caret to the Editor
+   *
+   * @param {boolean} atEnd - if true, set Caret to the end of the Editor
+   *
+   * @return {boolean}
+   */
+  focus(atEnd?: boolean): boolean;
+}

package/types/api/events.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Describes Editor`s events API
+ */
+export interface Events {
+  /**
+   * Emits event
+   *
+   * @param {string} eventName
+   * @param {any} data
+   */
+  emit(eventName: string, data: any): void;
+
+  /**
+   * Unsubscribe from event
+   *
+   * @param {string} eventName
+   * @param {(data: any) => void} callback
+   */
+  off(eventName: string, callback: (data?: any) => void): void;
+
+  /**
+   * Subscribe to event
+   *
+   * @param {string} eventName
+   * @param {(data: any) => void} callback
+   */
+  on(eventName: string, callback: (data?: any) => void): void;
+}

package/types/api/i18n.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Describes Editor`s I18n API
+ */
+export interface I18n {
+  /**
+   * Perform translation with automatically added namespace like `tools.${toolName}` or `blockTunes.${tuneName}`
+   *
+   * @param dictKey - what to translate
+   */
+  t(dictKey: string): string;
+}

package/types/api/index.d.ts

@@ -0,0 +1,17 @@
+export * from './blocks';
+export * from './events';
+export * from './listeners';
+export * from './sanitizer';
+export * from './saver';
+export * from './selection';
+export * from './styles';
+export * from './caret';
+export * from './toolbar';
+export * from './notifier';
+export * from './tooltip';
+export * from './inline-toolbar';
+export * from './block';
+export * from './readonly';
+export * from './i18n';
+export * from './ui';
+export * from './tools';

package/types/api/inline-toolbar.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Describes InlineToolbar API methods
+ */
+export interface InlineToolbar {
+    /**
+     * Closes InlineToolbar
+     */
+    close(): void;
+  
+    /**
+     * Opens InlineToolbar
+     */
+    open(): void;
+}
+  

package/types/api/listeners.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Describes Editor`s listeners API
+ */
+export interface Listeners {
+  /**
+   * Subscribe to event dispatched on passed element. Returns listener id.
+   *
+   * @param {Element} element
+   * @param {string} eventType
+   * @param {(event: Event) => void}handler
+   * @param {boolean} useCapture
+   */
+  on(element: Element, eventType: string, handler: (event?: Event) => void, useCapture?: boolean): string | undefined;
+
+  /**
+   * Unsubscribe from event dispatched on passed element
+   *
+   * @param {Element} element
+   * @param {string} eventType
+   * @param {(event: Event) => void}handler
+   * @param {boolean} useCapture
+   */
+  off(element: Element, eventType: string, handler: (event?: Event) => void, useCapture?: boolean): void;
+
+
+  /**
+   * Unsubscribe from event dispatched by the listener id
+   *
+   * @param id - id of the listener to remove
+   */
+  offById(id: string): void;
+}

package/types/api/notifier.d.ts

@@ -0,0 +1,14 @@
+import {ConfirmNotifierOptions, NotifierOptions, PromptNotifierOptions} from 'codex-notifier';
+
+/**
+ * Notifier API
+ */
+export interface Notifier {
+
+  /**
+   * Show web notification
+   *
+   * @param {NotifierOptions | ConfirmNotifierOptions | PromptNotifierOptions}
+   */
+  show: (options: NotifierOptions | ConfirmNotifierOptions | PromptNotifierOptions) => void;
+}

package/types/api/readonly.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ReadOnly API
+ */
+export interface ReadOnly {
+  /**
+   * Set or toggle read-only state
+   *
+   * @param {Boolean|undefined} state - set or toggle state
+   * @returns {Promise<boolean>} current value
+   */
+  toggle: (state?: boolean) => Promise<boolean>;
+
+  /**
+   * Contains current read-only state
+   */
+  isEnabled: boolean;
+}

package/types/api/sanitizer.d.ts

@@ -0,0 +1,14 @@
+import {SanitizerConfig} from '../index';
+
+/**
+ * Describes Editor`s sanitizer API
+ */
+export interface Sanitizer {
+  /**
+   * Clean taint string with html and returns clean string
+   *
+   * @param {string} taintString
+   * @param {SanitizerConfig} config - configuration for sanitizer
+   */
+  clean(taintString: string, config: SanitizerConfig): string;
+}

package/types/api/saver.d.ts

@@ -0,0 +1,13 @@
+import {OutputData} from '../data-formats/output-data';
+
+/**
+ * Describes Editor`s saver API
+ */
+export interface Saver {
+  /**
+   * Saves Editors data and returns promise with it
+   *
+   * @returns {Promise<OutputData>}
+   */
+  save(): Promise<OutputData>;
+}

package/types/api/selection.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Describes methods for work with Selections
+ */
+export interface Selection {
+  /**
+   * Looks ahead from selection and find passed tag with class name
+   * @param {string} tagName - tag to find
+   * @param {string} className - tag's class name
+   * @return {HTMLElement|null}
+   */
+  findParentTag(tagName: string, className?: string): HTMLElement|null;
+
+  /**
+   * Expand selection to passed tag
+   * @param {HTMLElement} node - tag that should contain selection
+   */
+  expandToTag(node: HTMLElement): void;
+
+  /**
+   * Sets fake background.
+   * Allows to imitate selection while focus moved away
+  */
+  setFakeBackground(): void;
+
+  /**
+   * Removes fake background
+   */
+  removeFakeBackground(): void;
+
+  /**
+   * Save selection range.
+   * Allows to save selection to be able to temporally move focus away.
+   * Might be useful for inline tools
+   */
+  save(): void;
+
+  /**
+   * Restore saved selection range
+   */
+  restore(): void;
+}

package/types/api/styles.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Describes styles API
+ */
+export interface Styles {
+  /**
+   * Main Editor`s block styles
+   */
+  block: string;
+
+  /**
+   * Styles for Inline Toolbar button
+   */
+  inlineToolButton: string;
+
+  /**
+   * Styles for active Inline Toolbar button
+   */
+  inlineToolButtonActive: string;
+
+  /**
+   * Styles for inputs
+   */
+  input: string;
+
+  /**
+   * Loader styles
+   */
+  loader: string;
+
+  /**
+   * Styles for Settings box buttons
+   */
+  settingsButton: string;
+
+  /**
+   * Styles for active Settings box buttons
+   */
+  settingsButtonActive: string;
+
+  /**
+   * Styles for buttons
+   */
+  button: string;
+}

package/types/api/toolbar.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Describes Toolbar API methods
+ */
+export interface Toolbar {
+  /**
+   * Closes Toolbar
+   */
+  close(): void;
+
+  /**
+   * Opens Toolbar
+   */
+  open(): void;
+
+  /**
+   * Toggles Block Setting of the current block
+   * @param {boolean} openingState —  opening state of Block Setting
+   */
+  toggleBlockSettings(openingState?: boolean): void;
+
+  /**
+   * Toggle toolbox
+   * @param {boolean} openingState —  opening state of the toolbox
+   */
+  toggleToolbox(openingState?: boolean): void;
+}

package/types/api/tools.d.ts

@@ -0,0 +1,11 @@
+import { BlockToolAdapter } from '../tools/adapters/block-tool-adapter';
+
+/**
+ * Describes methods for accessing installed Editor tools
+ */
+export interface Tools {
+  /**
+   * Returns all available Block Tools
+   */
+  getBlockTools(): BlockToolAdapter[];
+}

package/types/api/tooltip.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Tooltip API
+ */
+import {TooltipContent, TooltipOptions} from '../../src/components/utils/tooltip';
+
+export interface Tooltip {
+  /**
+   * Show tooltip
+   *
+   * @param {HTMLElement} element
+   * @param {TooltipContent} content
+   * @param {TooltipOptions} options
+   */
+  show: (element: HTMLElement, content: TooltipContent, options?: TooltipOptions) => void;
+
+  /**
+   * Hides tooltip
+   */
+  hide: () => void;
+
+  /**
+   * Decorator for showing Tooltip by mouseenter/mouseleave
+   *
+   * @param {HTMLElement} element
+   * @param {TooltipContent} content
+   * @param {TooltipOptions} options
+   */
+  onHover: (element: HTMLElement, content: TooltipContent, options?: TooltipOptions) => void;
+
+}

package/types/api/ui.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Describes API module allowing to access some Editor UI elements and methods
+ */
+export interface Ui {
+  /**
+   * Allows accessing some Editor UI elements
+   */
+  nodes: UiNodes,
+}
+
+/**
+ * Allows accessing some Editor UI elements
+ */
+export interface UiNodes {
+  /**
+   * Top-level editor instance wrapper
+   */
+  wrapper: HTMLElement,
+
+  /**
+   * Element that holds all the Blocks
+   */
+  redactor: HTMLElement,
+}

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

@@ -0,0 +1 @@
+export type BlockTuneData = any;