@jackuait/blok 0.4.1 → 0.4.2

package/src/components/tools/inline.ts

@@ -0,0 +1,71 @@
+import { BaseToolAdapter } from './base';
+import type { InlineTool as IInlineTool, InlineToolConstructable } from '@/types';
+import type { InlineToolAdapter as InlineToolAdapterInterface } from '@/types/tools/adapters/inline-tool-adapter';
+import { ToolType } from '@/types/tools/adapters/tool-type';
+
+/**
+ * InlineTool object to work with Inline Tools constructables
+ */
+export class InlineToolAdapter extends BaseToolAdapter<ToolType.Inline, IInlineTool> implements InlineToolAdapterInterface {
+  /**
+   * Tool type — Inline
+   */
+  public type: ToolType.Inline = ToolType.Inline;
+
+  /**
+   * Returns list of required methods that are missing on the inline tool prototype
+   * @param requiredMethods - method names that must be implemented
+   */
+  public getMissingMethods(requiredMethods: string[]): string[] {
+    const constructable = this.constructable as InlineToolConstructable | undefined;
+    const prototype = constructable?.prototype as Record<string, unknown> | undefined;
+
+    if (!prototype) {
+      return [ ...requiredMethods ];
+    }
+
+    return requiredMethods.filter((methodName) => typeof prototype[methodName] !== 'function');
+  }
+
+  /**
+   * Constructs new InlineTool instance from constructable
+   */
+  public create(): IInlineTool {
+
+    const InlineToolClass = this.constructable as InlineToolConstructable;
+
+    return new InlineToolClass({
+      api: this.api,
+      config: this.settings,
+    }) as IInlineTool;
+  }
+
+  /**
+   * Allows inline tool to be available in read-only mode
+   * Can be used, for example, by comments tool
+   */
+  public get isReadOnlySupported(): boolean {
+    const constructable = this.constructable as InlineToolConstructable | undefined;
+
+    return constructable?.isReadOnlySupported ?? false;
+  }
+
+  /**
+   * Returns title of the tool
+   */
+  public get title(): string {
+    const constructable = this.constructable as InlineToolConstructable;
+
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- Backward compatibility: title is deprecated but still needs to be supported
+    return constructable['title'] || '';
+  }
+
+  /**
+   * Returns the translation key for the tool title
+   */
+  public get titleKey(): string | undefined {
+    const constructable = this.constructable as InlineToolConstructable;
+
+    return constructable['titleKey'];
+  }
+}

package/src/components/tools/tune.ts

@@ -0,0 +1,33 @@
+import { BaseToolAdapter } from './base';
+import type { BlockAPI, BlockTune as IBlockTune, BlockTuneConstructable } from '@/types';
+import type { BlockTuneData } from '@/types/block-tunes/block-tune-data';
+import type { BlockTuneAdapter as BlockTuneAdapterInterface } from '@/types/tools/adapters/block-tune-adapter';
+import { ToolType } from '@/types/tools/adapters/tool-type';
+
+/**
+ * Stub class for BlockTunes
+ * @todo Implement
+ */
+export class BlockTuneAdapter extends BaseToolAdapter<ToolType.Tune, IBlockTune> implements BlockTuneAdapterInterface {
+  /**
+   * Tool type — Tune
+   */
+  public type: ToolType.Tune = ToolType.Tune;
+
+  /**
+   * Constructs new BlockTune instance from constructable
+   * @param data - Tune data
+   * @param block - Block API object
+   */
+  public create(data: BlockTuneData, block: BlockAPI): IBlockTune {
+     
+    const BlockTuneClass = this.constructable as BlockTuneConstructable;
+
+    return new BlockTuneClass({
+      api: this.api,
+      config: this.settings,
+      block,
+      data,
+    });
+  }
+}

package/src/components/ui/toolbox.ts

@@ -0,0 +1,497 @@
+import { beautifyShortcut, capitalize, isMobileScreen } from '../utils';
+import { Shortcuts } from '../utils/shortcuts';
+import type { BlockToolAdapter } from '../tools/block';
+import type { ToolsCollection } from '../tools/collection';
+import type { API, BlockToolData, ToolboxConfigEntry, PopoverItemParams, BlockAPI } from '@/types';
+import { EventsDispatcher } from '../utils/events';
+import { translateToolTitle, type I18nInstance } from '../utils/tools';
+import { PopoverEvent } from '@/types/utils/popover/popover-event';
+import { Listeners } from '../utils/listeners';
+import { Dom } from '../dom';
+import type { Popover } from '../utils/popover';
+import { PopoverDesktop, PopoverMobile } from '../utils/popover';
+import { BlokMobileLayoutToggled } from '../events';
+
+/**
+ * @todo the first Tab on the Block — focus Plus Button, the second — focus Block Tunes Toggler, the third — focus next Block
+ */
+
+/**
+ * Event that can be triggered by the Toolbox
+ */
+export enum ToolboxEvent {
+  /**
+   * When the Toolbox is opened
+   */
+  Opened = 'toolbox-opened',
+
+  /**
+   * When the Toolbox is closed
+   */
+  Closed = 'toolbox-closed',
+
+  /**
+   * When the new Block added by Toolbox
+   */
+  BlockAdded = 'toolbox-block-added',
+}
+
+/**
+ * Events fired by the Toolbox
+ *
+ * Event name -> payload
+ */
+export interface ToolboxEventMap {
+  [ToolboxEvent.Opened]: undefined;
+  [ToolboxEvent.Closed]: undefined;
+  [ToolboxEvent.BlockAdded]: {
+    block: BlockAPI
+  };
+}
+
+/**
+ * Available i18n dict keys that should be passed to the constructor
+ */
+type ToolboxTextLabelsKeys = 'filter' | 'nothingFound';
+
+/**
+ * Toolbox
+ * This UI element contains list of Block Tools available to be inserted
+ * It appears after click on the Plus Button
+ * @implements {EventsDispatcher} with some events, see {@link ToolboxEvent}
+ */
+export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
+  /**
+   * Returns True if Toolbox is Empty and nothing to show
+   * @returns {boolean}
+   */
+  public get isEmpty(): boolean {
+    return this.toolsToBeDisplayed.length === 0;
+  }
+
+  /**
+   * Opening state
+   * @type {boolean}
+   */
+  public opened = false;
+
+  /**
+   * Listeners util instance
+   */
+  protected listeners: Listeners = new Listeners();
+
+  /**
+   * Blok API
+   */
+  private api: API;
+
+  /**
+   * Popover instance. There is a util for vertical lists.
+   * Null until initialized
+   */
+  private popover: Popover | null = null;
+
+  /**
+   * List of Tools available. Some of them will be shown in the Toolbox
+   */
+  private tools: ToolsCollection<BlockToolAdapter>;
+
+  /**
+   * Cache for tools to be displayed
+   */
+  private _toolsToBeDisplayed: BlockToolAdapter[] | undefined;
+
+  /**
+   * Cache for toolbox items to be displayed
+   */
+  private _toolboxItemsToBeDisplayed: PopoverItemParams[] | undefined;
+
+  /**
+   * Text labels used in the Toolbox. Should be passed from the i18n module
+   */
+  private i18nLabels: Record<ToolboxTextLabelsKeys, string>;
+
+  /**
+   * I18n instance for translations
+   */
+  private i18n: I18nInstance;
+
+  /**
+   * Current module HTML Elements
+   */
+  private nodes: {
+    toolbox: HTMLElement;
+  } ;
+
+  /**
+   * CSS styles
+   * @deprecated Use data attributes for identification instead
+   */
+  private static get CSS(): {
+    toolbox: string;
+    } {
+    return {
+      toolbox: '',
+    };
+  }
+
+  /**
+   * Element relative to which the popover should be positioned
+   */
+  private triggerElement?: HTMLElement;
+
+  /**
+   * Toolbox constructor
+   * @param options - available parameters
+   * @param options.api - Blok API methods
+   * @param options.tools - Tools available to check whether some of them should be displayed at the Toolbox or not
+   * @param options.i18n - I18n instance for translations
+   * @param options.triggerElement - Element relative to which the popover should be positioned
+   */
+  constructor({ api, tools, i18nLabels, i18n, triggerElement }: {
+    api: API;
+    tools: ToolsCollection<BlockToolAdapter>;
+    i18nLabels: Record<ToolboxTextLabelsKeys, string>;
+    i18n: I18nInstance;
+    triggerElement?: HTMLElement;
+  }) {
+    super();
+
+    this.api = api;
+    this.tools = tools;
+    this.i18nLabels = i18nLabels;
+    this.i18n = i18n;
+    this.triggerElement = triggerElement;
+
+    this.enableShortcuts();
+
+    this.nodes = {
+      toolbox: Dom.make('div'),
+    };
+    this.nodes.toolbox.setAttribute('data-blok-testid', 'toolbox');
+
+    this.initPopover();
+
+    this.api.events.on(BlokMobileLayoutToggled, this.handleMobileLayoutToggle);
+  }
+
+  /**
+   * Returns root block settings element
+   */
+  public getElement(): HTMLElement | null {
+    return this.nodes.toolbox;
+  }
+
+  /**
+   * Checks if the element is contained in the Toolbox or its Popover
+   * @param element - element to check
+   */
+  public contains(element: HTMLElement): boolean {
+    if (this.nodes.toolbox.contains(element)) {
+      return true;
+    }
+
+    if (this.popover?.getElement().contains(element)) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Returns true if the Toolbox has the Flipper activated and the Flipper has selected button
+   */
+  public hasFocus(): boolean | undefined {
+    if (this.popover === null) {
+      return;
+    }
+
+    return 'hasFocus' in this.popover ? this.popover.hasFocus() : undefined;
+  }
+
+  /**
+   * Destroy Module
+   */
+  public destroy(): void {
+    super.destroy();
+
+    if (this.nodes && this.nodes.toolbox) {
+      this.nodes.toolbox.remove();
+    }
+
+    this.removeAllShortcuts();
+    this.popover?.off(PopoverEvent.Closed, this.onPopoverClose);
+    this.listeners.destroy();
+    this.api.events.off(BlokMobileLayoutToggled, this.handleMobileLayoutToggle);
+  }
+
+  /**
+   * Toolbox Tool's button click handler
+   * @param toolName - tool type to be activated
+   * @param blockDataOverrides - Block data predefined by the activated Toolbox item
+   */
+  public async toolButtonActivated(toolName: string, blockDataOverrides?: BlockToolData): Promise<void> {
+    await this.insertNewBlock(toolName, blockDataOverrides);
+  }
+
+  /**
+   * Open Toolbox with Tools
+   */
+  public open(): void {
+    if (this.isEmpty) {
+      return;
+    }
+
+    this.popover?.show();
+    this.opened = true;
+    this.emit(ToolboxEvent.Opened);
+  }
+
+  /**
+   * Close Toolbox
+   */
+  public close(): void {
+    this.popover?.hide();
+    this.opened = false;
+    this.emit(ToolboxEvent.Closed);
+  }
+
+  /**
+   * Close Toolbox
+   */
+  public toggle(): void {
+    if (!this.opened) {
+      this.open();
+    } else {
+      this.close();
+    }
+  }
+
+  /**
+   * Destroys existing popover instance and contructs the new one.
+   */
+  public handleMobileLayoutToggle = (): void  => {
+    this.destroyPopover();
+    this.initPopover();
+  };
+
+  /**
+   * Creates toolbox popover and appends it inside wrapper element
+   */
+  private initPopover(): void {
+    const PopoverClass = isMobileScreen() ? PopoverMobile : PopoverDesktop;
+
+    this.popover = new PopoverClass({
+      scopeElement: this.api.ui.nodes.redactor,
+      trigger: this.triggerElement || this.nodes.toolbox,
+      messages: {
+        nothingFound: this.i18nLabels.nothingFound,
+        search: this.i18nLabels.filter,
+      },
+      items: this.toolboxItemsToBeDisplayed,
+    });
+
+    this.popover.on(PopoverEvent.Closed, this.onPopoverClose);
+    this.popover.getElement().setAttribute('data-blok-testid', 'toolbox-popover');
+  }
+
+  /**
+   * Destroys popover instance and removes it from DOM
+   */
+  private destroyPopover(): void {
+    if (this.popover !== null) {
+      this.popover.hide();
+      this.popover.off(PopoverEvent.Closed, this.onPopoverClose);
+      this.popover.destroy();
+      this.popover = null;
+    }
+
+    if (this.nodes.toolbox !== null) {
+      this.nodes.toolbox.innerHTML = '';
+    }
+  }
+
+  /**
+   * Handles popover close event
+   */
+  private onPopoverClose = (): void => {
+    this.opened = false;
+    this.emit(ToolboxEvent.Closed);
+  };
+
+  /**
+   * Returns list of tools that enables the Toolbox (by specifying the 'toolbox' getter)
+   */
+  private get toolsToBeDisplayed(): BlockToolAdapter[] {
+    if (this._toolsToBeDisplayed) {
+      return this._toolsToBeDisplayed;
+    }
+
+    const result: BlockToolAdapter[] = [];
+
+    this.tools.forEach((tool) => {
+      const toolToolboxSettings = tool.toolbox;
+
+      if (toolToolboxSettings) {
+        result.push(tool);
+      }
+    });
+
+    this._toolsToBeDisplayed = result;
+
+    return result;
+  }
+
+  /**
+   * Returns list of items that will be displayed in toolbox
+   */
+  private get toolboxItemsToBeDisplayed(): PopoverItemParams[] {
+    if (this._toolboxItemsToBeDisplayed) {
+      return this._toolboxItemsToBeDisplayed;
+    }
+
+    /**
+     * Maps tool data to popover item structure
+     */
+    const toPopoverItem = (toolboxItem: ToolboxConfigEntry, tool: BlockToolAdapter, displaySecondaryLabel = true): PopoverItemParams => {
+      return {
+        icon: toolboxItem.icon,
+        title: translateToolTitle(this.i18n, toolboxItem, capitalize(tool.name)),
+        name: toolboxItem.name ?? tool.name,
+        onActivate: (): void => {
+          void this.toolButtonActivated(tool.name, toolboxItem.data);
+        },
+        secondaryLabel: (tool.shortcut && displaySecondaryLabel) ? beautifyShortcut(tool.shortcut) : '',
+      };
+    };
+
+    const result = this.toolsToBeDisplayed
+      .reduce<PopoverItemParams[]>((acc, tool) => {
+        const { toolbox } = tool;
+
+        if (toolbox === undefined) {
+          return acc;
+        }
+
+        const items = Array.isArray(toolbox) ? toolbox : [ toolbox ];
+
+        items.forEach((item, index) => {
+          acc.push(toPopoverItem(item, tool, index === 0));
+        });
+
+        return acc;
+      }, []);
+
+    this._toolboxItemsToBeDisplayed = result;
+
+    return result;
+  }
+
+  /**
+   * Iterate all tools and enable theirs shortcuts if specified
+   */
+  private enableShortcuts(): void {
+    this.toolsToBeDisplayed.forEach((tool: BlockToolAdapter) => {
+      const shortcut = tool.shortcut;
+
+      if (shortcut) {
+        this.enableShortcutForTool(tool.name, shortcut);
+      }
+    });
+  }
+
+  /**
+   * Enable shortcut Block Tool implemented shortcut
+   * @param {string} toolName - Tool name
+   * @param {string} shortcut - shortcut according to the ShortcutData Module format
+   */
+  private enableShortcutForTool(toolName: string, shortcut: string): void {
+    Shortcuts.add({
+      name: shortcut,
+      on: this.api.ui.nodes.redactor,
+      handler: async (event: KeyboardEvent) => {
+        event.preventDefault();
+
+        const currentBlockIndex = this.api.blocks.getCurrentBlockIndex();
+        const currentBlock = this.api.blocks.getBlockByIndex(currentBlockIndex);
+
+        /**
+         * Try to convert current Block to shortcut's tool
+         * If conversion is not possible, insert a new Block below
+         */
+        if (currentBlock) {
+          try {
+            const newBlock = await this.api.blocks.convert(currentBlock.id, toolName);
+
+            this.api.caret.setToBlock(newBlock, 'end');
+
+            return;
+          } catch (_error) {}
+        }
+
+        await this.insertNewBlock(toolName);
+      },
+    });
+  }
+
+  /**
+   * Removes all added shortcuts
+   * Fired when the Read-Only mode is activated
+   */
+  private removeAllShortcuts(): void {
+    this.toolsToBeDisplayed.forEach((tool: BlockToolAdapter) => {
+      const shortcut = tool.shortcut;
+
+      if (shortcut) {
+        Shortcuts.remove(this.api.ui.nodes.redactor, shortcut);
+      }
+    });
+  }
+
+  /**
+   * Inserts new block
+   * Can be called when button clicked on Toolbox or by ShortcutData
+   * @param {string} toolName - Tool name
+   * @param blockDataOverrides - predefined Block data
+   */
+  private async insertNewBlock(toolName: string, blockDataOverrides?: BlockToolData): Promise<void> {
+    const currentBlockIndex = this.api.blocks.getCurrentBlockIndex();
+    const currentBlock = this.api.blocks.getBlockByIndex(currentBlockIndex);
+
+    if (!currentBlock) {
+      return;
+    }
+
+    /**
+     * On mobile version, we see the Plus Button even near non-empty blocks,
+     * so if current block is not empty, add the new block below the current
+     */
+    const index = currentBlock.isEmpty ? currentBlockIndex : currentBlockIndex + 1;
+
+    const hasBlockDataOverrides = blockDataOverrides !== undefined && Object.keys(blockDataOverrides as Record<string, unknown>).length > 0;
+
+    const blockData: BlockToolData | undefined = hasBlockDataOverrides
+      ? Object.assign(await this.api.blocks.composeBlockData(toolName), blockDataOverrides)
+      : undefined;
+
+    const newBlock = this.api.blocks.insert(
+      toolName,
+      blockData,
+      undefined,
+      index,
+      undefined,
+      currentBlock.isEmpty
+    );
+
+    this.api.caret.setToBlock(index);
+
+    this.emit(ToolboxEvent.BlockAdded, {
+      block: newBlock,
+    });
+
+    /**
+     * close toolbar when node is changed
+     */
+    this.api.toolbar.close();
+  }
+}