@jackuait/blok 0.4.1-beta.0 → 0.4.1-beta.11

package/src/blok.ts

@@ -0,0 +1,267 @@
+'use strict';
+
+import type { BlokConfig, API } from '../types';
+import type { BlokModules } from './types-internal/blok-modules';
+
+/**
+ * Apply polyfills
+ */
+import '@babel/register';
+
+import './components/polyfills';
+import { Core } from './components/core';
+import { getBlokVersion, isObject, isFunction } from './components/utils';
+import { destroy as destroyTooltip } from './components/utils/tooltip';
+import { DATA_ATTR } from './components/constants/data-attributes';
+
+/**
+ * Export version as a named export
+ */
+export const version = getBlokVersion();
+
+/**
+ * Re-export DATA_ATTR for querying editor elements
+ */
+export { DATA_ATTR } from './components/constants/data-attributes';
+
+/**
+ * Blok
+ * @license Apache-2.0
+ */
+class Blok {
+  /**
+   * Store user-provided configuration for later export
+   */
+  private readonly initialConfiguration: BlokConfig|string|undefined;
+
+  /**
+   * Promise that resolves when core modules are ready and UI is rendered on the page
+   */
+  public isReady: Promise<void>;
+
+  /**
+   * Stores destroy method implementation.
+   * Clear heap occupied by Blok and remove UI components from the DOM.
+   */
+  public destroy: () => void;
+
+  /** Blok version */
+  public static get version(): string {
+    return getBlokVersion();
+  }
+
+  /**
+   * Data attributes used by the editor.
+   * Single source of truth for all data-blok-* attributes.
+   *
+   * @example
+   * // Query editor elements
+   * document.querySelectorAll(`[${Blok.DATA_ATTR.element}]`);
+   *
+   * // Check if block is selected
+   * block.getAttribute(Blok.DATA_ATTR.selected) === 'true';
+   */
+  public static DATA_ATTR = DATA_ATTR;
+
+  /**
+   * @param {BlokConfig|string|undefined} [configuration] - user configuration
+   */
+  constructor(configuration?: BlokConfig|string) {
+    this.initialConfiguration = isObject(configuration)
+      ? { ...configuration }
+      : configuration;
+
+    /**
+     * Set default onReady function or use the one from configuration if provided
+     */
+
+    const onReady = (isObject(configuration) && isFunction(configuration.onReady))
+      ? configuration.onReady
+      : () => {};
+
+    /**
+     * Create a Blok instance
+     */
+    const blok = new Core(configuration);
+
+    /**
+     * Initialize destroy with a no-op function that will be replaced in exportAPI
+     */
+
+    this.destroy = (): void => {};
+
+    /**
+     * We need to export isReady promise in the constructor
+     * as it can be used before other API methods are exported
+     * @type {Promise<void>}
+     */
+    this.isReady = blok.isReady.then(() => {
+      this.exportAPI(blok);
+      /**
+       * @todo pass API as an argument. It will allow to use Blok's API when blok is ready
+       */
+      onReady();
+    });
+  }
+
+  /**
+   * Export external API methods
+   * @param {Core} blok — Blok's instance
+   */
+  public exportAPI(blok: Core): void {
+    const fieldsToExport = [ 'configuration' ];
+    const destroy = (): void => {
+      Object.values(blok.moduleInstances)
+        .forEach((moduleInstance) => {
+          if (moduleInstance === undefined || moduleInstance === null) {
+            return;
+          }
+
+          if (isFunction((moduleInstance as { destroy?: () => void }).destroy)) {
+            (moduleInstance as { destroy: () => void }).destroy();
+          }
+
+          const listeners = (moduleInstance as { listeners?: { removeAll?: () => void } }).listeners;
+
+          if (listeners && isFunction(listeners.removeAll)) {
+            listeners.removeAll();
+          }
+        });
+
+      destroyTooltip();
+
+      for (const field in this) {
+        if (Object.prototype.hasOwnProperty.call(this, field)) {
+          delete (this as Record<string, unknown>)[field];
+        }
+      }
+
+      Object.setPrototypeOf(this, null);
+    };
+
+    fieldsToExport.forEach((field) => {
+      if (field !== 'configuration') {
+        (this as Record<string, unknown>)[field] = (blok as unknown as Record<string, unknown>)[field];
+
+        return;
+      }
+
+      const coreConfiguration = (blok as unknown as { configuration?: BlokConfig|string|undefined }).configuration;
+      const configurationToExport = isObject(this.initialConfiguration)
+        ? this.initialConfiguration
+        : coreConfiguration ?? this.initialConfiguration;
+
+      if (configurationToExport === undefined) {
+        return;
+      }
+
+      (this as Record<string, unknown>)[field] = configurationToExport as BlokConfig|string;
+    });
+
+    this.destroy = destroy;
+
+    const apiMethods = blok.moduleInstances.API.methods;
+    const eventsDispatcherApi = blok.moduleInstances.EventsAPI?.methods ?? apiMethods.events;
+
+    if (eventsDispatcherApi !== undefined) {
+      const defineDispatcher = (target: object): void => {
+        if (!Object.prototype.hasOwnProperty.call(target, 'eventsDispatcher')) {
+          Object.defineProperty(target, 'eventsDispatcher', {
+            value: eventsDispatcherApi,
+            configurable: true,
+            enumerable: true,
+            writable: false,
+          });
+        }
+      };
+
+      defineDispatcher(apiMethods);
+      defineDispatcher(this as Record<string, unknown>);
+    }
+
+    if (Object.getPrototypeOf(apiMethods) !== Blok.prototype) {
+      Object.setPrototypeOf(apiMethods, Blok.prototype);
+    }
+
+    Object.setPrototypeOf(this, apiMethods);
+
+    const moduleAliases = Object.create(null) as Record<string, unknown>;
+    const moduleInstances = blok.moduleInstances as Partial<BlokModules>;
+    const moduleInstancesRecord = moduleInstances as unknown as Record<string, unknown>;
+
+    const getAliasName = (name: string): string => (
+      /^[A-Z]+$/.test(name)
+        ? name.toLowerCase()
+        : name.charAt(0).toLowerCase() + name.slice(1)
+    );
+
+    Object.keys(moduleInstancesRecord)
+      .forEach((name) => {
+        const alias = getAliasName(name);
+
+        Object.defineProperty(moduleAliases, alias, {
+          configurable: true,
+          enumerable: true,
+          get: () => moduleInstancesRecord[name],
+        });
+      });
+
+    type ToolbarModuleWithSettings = {
+      blockSettings?: unknown;
+      inlineToolbar?: unknown;
+    };
+
+    const toolbarModule = moduleInstances.Toolbar as unknown as ToolbarModuleWithSettings | undefined;
+    const blockSettingsModule = moduleInstances.BlockSettings;
+
+    if (toolbarModule !== undefined && blockSettingsModule !== undefined && toolbarModule.blockSettings === undefined) {
+      toolbarModule.blockSettings = blockSettingsModule;
+    }
+
+    const inlineToolbarModule = moduleInstances.InlineToolbar;
+
+    if (toolbarModule !== undefined && inlineToolbarModule !== undefined && toolbarModule.inlineToolbar === undefined) {
+      toolbarModule.inlineToolbar = inlineToolbarModule;
+    }
+
+    Object.defineProperty(this, 'module', {
+      value: moduleAliases,
+      configurable: true,
+      enumerable: false,
+      writable: false,
+    });
+
+    delete (this as Partial<Blok>).exportAPI;
+
+    const shorthands = {
+      blocks: {
+        clear: 'clear',
+        render: 'render',
+      },
+      caret: {
+        focus: 'focus',
+      },
+      events: {
+        on: 'on',
+        off: 'off',
+        emit: 'emit',
+      },
+      saver: {
+        save: 'save',
+      },
+    };
+
+    Object.entries(shorthands)
+      .forEach(([key, methods]) => {
+        Object.entries(methods)
+          .forEach(([name, alias]) => {
+            const apiKey = key as keyof API;
+            const apiMethodGroup = blok.moduleInstances.API.methods[apiKey] as unknown as Record<string, unknown>;
+
+            (this as Record<string, unknown>)[alias] = apiMethodGroup[name];
+          });
+      });
+  }
+}
+
+export { Blok };

package/src/components/__module.ts

@@ -0,0 +1,139 @@
+import type { BlokModules } from '../types-internal/blok-modules';
+import type { BlokConfig } from '../../types';
+import type { ModuleConfig } from '../types-internal/module-config';
+import { Listeners } from './utils/listeners';
+import type { EventsDispatcher } from './utils/events';
+import type { BlokEventMap } from './events';
+
+/**
+ * The type <T> of the Module generic.
+ * It describes the structure of nodes used in modules.
+ */
+export type ModuleNodes = object;
+
+/**
+ * @abstract
+ * @class      Module
+ * @classdesc  All modules inherits from this class.
+ * @typedef {Module} Module
+ * @property {object} config - Blok user settings
+ * @property {BlokModules} Blok - List of Blok modules
+ */
+export class Module<T extends ModuleNodes = Record<string, HTMLElement>> {
+  /**
+   * Each module can provide some UI elements that will be stored in this property
+   */
+   
+  public nodes: T = {} as any;
+
+  /**
+   * Blok modules list
+   * @type {BlokModules}
+   */
+  protected Blok: BlokModules;
+
+  /**
+   * Blok configuration object
+   * @type {BlokConfig}
+   */
+  protected config: BlokConfig;
+
+  /**
+   * Blok event dispatcher class
+   */
+  protected eventsDispatcher: EventsDispatcher<BlokEventMap>;
+
+  /**
+   * Util for bind/unbind DOM event listeners
+   */
+  protected listeners: Listeners = new Listeners();
+
+  /**
+   * This object provides methods to push into set of listeners that being dropped when read-only mode is enabled
+   */
+  protected readOnlyMutableListeners = {
+    /**
+     * Assigns event listener on DOM element and pushes into special array that might be removed
+     * @param {EventTarget} element - DOM Element
+     * @param {string} eventType - Event name
+     * @param {Function} handler - Event handler
+     * @param {boolean|AddEventListenerOptions} options - Listening options
+     */
+    on: (
+      element: EventTarget,
+      eventType: string,
+      handler: (event: Event) => void,
+      options: boolean | AddEventListenerOptions = false
+    ): void => {
+      const listenerId = this.listeners.on(element, eventType, handler, options);
+
+      if (listenerId) {
+        this.mutableListenerIds.push(listenerId);
+      }
+    },
+
+    /**
+     * Clears all mutable listeners
+     */
+    clearAll: (): void => {
+      for (const id of this.mutableListenerIds) {
+        this.listeners.offById(id);
+      }
+
+      this.mutableListenerIds = [];
+    },
+  };
+
+  /**
+   * The set of listener identifiers which will be dropped in read-only mode
+   */
+  private mutableListenerIds: string[] = [];
+
+  /**
+   * @class
+   * @param options - Module options
+   * @param options.config - Module config
+   * @param options.eventsDispatcher - Common event bus
+   */
+  constructor({ config, eventsDispatcher }: ModuleConfig) {
+    if (new.target === Module) {
+      throw new TypeError('Constructors for abstract class Module are not allowed.');
+    }
+
+    this.config = config;
+    this.eventsDispatcher = eventsDispatcher;
+    // Blok is initialized via the state setter after construction
+    this.Blok = {} as BlokModules;
+  }
+
+  /**
+   * Blok modules setter
+   * @param {BlokModules} Blok - Blok's Modules
+   */
+  public set state(Blok: BlokModules) {
+    this.Blok = Blok;
+  }
+
+  /**
+   * Remove memorized nodes
+   */
+  public removeAllNodes(): void {
+    for (const key in this.nodes) {
+      const node = this.nodes[key];
+
+      if (node instanceof HTMLElement) {
+        node.remove();
+      }
+    }
+  }
+
+  /**
+   * Returns true if current direction is RTL (Right-To-Left).
+   *
+   * This reads from config.i18n.direction which is set by the I18n module during prepare().
+   * Should only be accessed after modules have been initialized.
+   */
+  protected get isRtl(): boolean {
+    return this.config.i18n?.direction === 'rtl';
+  }
+}

package/src/components/block/api.ts

@@ -0,0 +1,155 @@
+import type { Block } from './index';
+import type { BlockToolData, ToolConfig, ToolboxConfigEntry } from '../../../types/tools';
+import type { SavedData } from '../../../types/data-formats';
+import type { BlockAPI as BlockAPIInterface } from '../../../types/api';
+
+/**
+ * Constructs new BlockAPI object
+ * @class
+ * @param {Block} block - Block to expose
+ */
+const BlockAPIConstructor = function BlockAPI(
+  this: BlockAPIInterface,
+  block: Block
+): BlockAPIInterface {
+  const blockAPI: BlockAPIInterface = {
+    /**
+     * Block id
+     * @returns {string}
+     */
+    get id(): string {
+      return block.id;
+    },
+    /**
+     * Tool name
+     * @returns {string}
+     */
+    get name(): string {
+      return block.name;
+    },
+
+    /**
+     * Tool config passed on Blok's initialization
+     * @returns {ToolConfig}
+     */
+    get config(): ToolConfig {
+      return block.config;
+    },
+
+    /**
+     * Element, that wraps plugin contents
+     * @returns {HTMLElement}
+     */
+    get holder(): HTMLElement {
+      return block.holder;
+    },
+
+    /**
+     * True if Block content is empty
+     * @returns {boolean}
+     */
+    get isEmpty(): boolean {
+      return block.isEmpty;
+    },
+
+    /**
+     * True if Block is selected with Cross-Block selection
+     * @returns {boolean}
+     */
+    get selected(): boolean {
+      return block.selected;
+    },
+
+    /**
+     * Set Block's stretch state
+     * @param {boolean} state — state to set
+     */
+    set stretched(state: boolean) {
+      block.setStretchState(state);
+    },
+
+    /**
+     * True if Block is stretched
+     * @returns {boolean}
+     */
+    get stretched(): boolean {
+      return block.stretched;
+    },
+
+    /**
+     * True if Block has inputs to be focused
+     */
+    get focusable(): boolean {
+      return block.focusable;
+    },
+
+    /**
+     * Call Tool method with errors handler under-the-hood
+     * @param {string} methodName - method to call
+     * @param {object} param - object with parameters
+     * @returns {unknown}
+     */
+    call(methodName: string, param?: object): unknown {
+      return block.call(methodName, param);
+    },
+
+    /**
+     * Save Block content
+     * @returns {Promise<void|SavedData>}
+     */
+    save(): Promise<void|SavedData> {
+      return block.save();
+    },
+
+    /**
+     * Validate Block data
+     * @param {BlockToolData} data - data to validate
+     * @returns {Promise<boolean>}
+     */
+    validate(data: BlockToolData): Promise<boolean> {
+      return block.validate(data);
+    },
+
+    /**
+     * Allows to say Blok that Block was changed. Used to manually trigger Blok's 'onChange' callback
+     * Can be useful for block changes invisible for blok core.
+     */
+    dispatchChange(): void {
+      block.dispatchChange();
+    },
+
+    /**
+     * 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> {
+      return block.getActiveToolboxEntry();
+    },
+  };
+
+  Object.setPrototypeOf(this, blockAPI);
+
+  Object.defineProperties(this, {
+    id: {
+      get(): string {
+        return block.id;
+      },
+      enumerable: true,
+      configurable: true,
+    },
+    name: {
+      get(): string {
+        return block.name;
+      },
+      enumerable: true,
+      configurable: true,
+    },
+  });
+
+  return this;
+};
+
+// Export BlockAPI with proper constructor type
+export const BlockAPI = BlockAPIConstructor as unknown as {
+  new (block: Block): BlockAPIInterface;
+};