feat(popover): custom content becomes a popover item (#2707)

* Add custom item

* Remove customcontent parameter from popover

* Tests

* Cleanup

* Cleanup

* Lint

* Cleanup

* Rename custom to html, add enum with item types

* Fix tests

* Add order test

* Update jsdoc

* Update changelog

* Fix issue with html item not hiding on search

* Fix flipper issue

* Update changelog

Author: TatianaFomina

docs/CHANGELOG.md

@@ -15,6 +15,7 @@
 - `Fix` - Caret lost after block conversion on mobile devices.
 - `Improvement` - The API `blocks.convert()` now returns the new block API
 - `Improvement` - The API `caret.setToBlock()` now can accept either BlockAPI or block index or block id
+- `New` – *Menu Config* – New item type – HTML
 
 ### 2.29.1
 

src/components/block/index.ts

@@ -21,11 +21,12 @@ import BlockTune from '../tools/tune';
 import { BlockTuneData } from '../../../types/block-tunes/block-tune-data';
 import ToolsCollection from '../tools/collection';
 import EventsDispatcher from '../utils/events';
-import { TunesMenuConfig, TunesMenuConfigItem } from '../../../types/tools';
+import { TunesMenuConfigItem } from '../../../types/tools';
 import { isMutationBelongsToElement } from '../utils/mutations';
 import { EditorEventMap, FakeCursorAboutToBeToggled, FakeCursorHaveBeenSet, RedactorDomChanged } from '../events';
 import { RedactorDomChangedPayload } from '../events/RedactorDomChanged';
 import { convertBlockDataToString, isSameBlockData } from '../utils/blocks';
+import { PopoverItemType } from '../utils/popover';
 
 /**
  * Interface describes Block class constructor argument
@@ -610,29 +611,28 @@ export default class Block extends EventsDispatcher<BlockEvents> {
   }
 
   /**
-   * Returns data to render in tunes menu.
-   * Splits block tunes into 3 groups: block specific tunes, common tunes
-   * and custom html that is produced by combining tunes html from both previous groups
+   * Returns data to render in Block Tunes menu.
+   * Splits block tunes into 2 groups: block specific tunes and common tunes
    */
   public getTunes(): {
     toolTunes: PopoverItemParams[];
     commonTunes: PopoverItemParams[];
-    customHtmlTunes: HTMLElement
     } {
-    const customHtmlTunesContainer = document.createElement('div');
+    const toolTunesPopoverParams: TunesMenuConfigItem[] = [];
     const commonTunesPopoverParams: TunesMenuConfigItem[] = [];
 
     /** Tool's tunes: may be defined as return value of optional renderSettings method */
     const tunesDefinedInTool = typeof this.toolInstance.renderSettings === 'function' ? this.toolInstance.renderSettings() : [];
 
-    /** Separate custom html from Popover items params for tool's tunes */
-    const {
-      items: toolTunesPopoverParams,
-      htmlElement: toolTunesHtmlElement,
-    } = this.getTunesDataSegregated(tunesDefinedInTool);
-
-    if (toolTunesHtmlElement !== undefined) {
-      customHtmlTunesContainer.appendChild(toolTunesHtmlElement);
+    if ($.isElement(tunesDefinedInTool)) {
+      toolTunesPopoverParams.push({
+        type: PopoverItemType.Html,
+        element: tunesDefinedInTool,
+      });
+    } else if (Array.isArray(tunesDefinedInTool)) {
+      toolTunesPopoverParams.push(...tunesDefinedInTool);
+    } else {
+      toolTunesPopoverParams.push(tunesDefinedInTool);
     }
 
     /** Common tunes: combination of default tunes (move up, move down, delete) and third-party tunes connected via tunes api */
@@ -643,28 +643,24 @@ export default class Block extends EventsDispatcher<BlockEvents> {
 
     /** Separate custom html from Popover items params for common tunes */
     commonTunes.forEach(tuneConfig => {
-      const {
-        items,
-        htmlElement,
-      } = this.getTunesDataSegregated(tuneConfig);
-
-      if (htmlElement !== undefined) {
-        customHtmlTunesContainer.appendChild(htmlElement);
-      }
-
-      if (items !== undefined) {
-        commonTunesPopoverParams.push(...items);
+      if ($.isElement(tuneConfig)) {
+        commonTunesPopoverParams.push({
+          type: PopoverItemType.Html,
+          element: tuneConfig,
+        });
+      } else if (Array.isArray(tuneConfig)) {
+        commonTunesPopoverParams.push(...tuneConfig);
+      } else {
+        commonTunesPopoverParams.push(tuneConfig);
       }
     });
 
     return {
       toolTunes: toolTunesPopoverParams,
       commonTunes: commonTunesPopoverParams,
-      customHtmlTunes: customHtmlTunesContainer,
     };
   }
 
-
   /**
    * Update current input index with selection anchor node
    */
@@ -750,25 +746,6 @@ export default class Block extends EventsDispatcher<BlockEvents> {
     return convertBlockDataToString(blockData, this.tool.conversionConfig);
   }
 
-  /**
-   * Determines if tool's tunes settings are custom html or popover params and separates one from another by putting to different object fields
-   *
-   * @param tunes - tool's tunes config
-   */
-  private getTunesDataSegregated(tunes: HTMLElement | TunesMenuConfig): { htmlElement?: HTMLElement; items: PopoverItemParams[] } {
-    const result = { } as { htmlElement?: HTMLElement; items: PopoverItemParams[] };
-
-    if ($.isElement(tunes)) {
-      result.htmlElement = tunes as HTMLElement;
-    } else if (Array.isArray(tunes)) {
-      result.items = tunes as PopoverItemParams[];
-    } else {
-      result.items = [ tunes ];
-    }
-
-    return result;
-  }
-
   /**
    * Make default Block wrappers and put Tool`s content there
    *

src/components/modules/toolbar/blockSettings.ts

@@ -7,7 +7,7 @@ import { I18nInternalNS } from '../../i18n/namespace-internal';
 import Flipper from '../../flipper';
 import { TunesMenuConfigItem } from '../../../../types/tools';
 import { resolveAliases } from '../../utils/resolve-aliases';
-import { type Popover, PopoverDesktop, PopoverMobile, PopoverItemParams, PopoverItemDefaultParams } from '../../utils/popover';
+import { type Popover, PopoverDesktop, PopoverMobile, PopoverItemParams, PopoverItemDefaultParams, PopoverItemType } from '../../utils/popover';
 import { PopoverEvent } from '../../utils/popover/popover.types';
 import { isMobileScreen } from '../../utils';
 import { EditorMobileLayoutToggled } from '../../events';
@@ -124,7 +124,7 @@ export default class BlockSettings extends Module<BlockSettingsNodes> {
     this.Editor.BlockSelection.clearCache();
 
     /** Get tool's settings data */
-    const { toolTunes, commonTunes, customHtmlTunes } = targetBlock.getTunes();
+    const { toolTunes, commonTunes } = targetBlock.getTunes();
 
     /** Tell to subscribers that block settings is opened */
     this.eventsDispatcher.emit(this.events.opened);
@@ -134,8 +134,6 @@ export default class BlockSettings extends Module<BlockSettingsNodes> {
     this.popover = new PopoverClass({
       searchable: true,
       items: await this.getTunesItems(targetBlock, commonTunes, toolTunes),
-      customContent: customHtmlTunes,
-      customContentFlippableItems: this.getControls(customHtmlTunes),
       scopeElement: this.Editor.API.methods.ui.nodes.redactor,
       messages: {
         nothingFound: I18n.ui(I18nInternalNS.ui.popover, 'Nothing found'),
@@ -212,7 +210,7 @@ export default class BlockSettings extends Module<BlockSettingsNodes> {
     if (toolTunes !== undefined && toolTunes.length > 0) {
       items.push(...toolTunes);
       items.push({
-        type: 'separator',
+        type: PopoverItemType.Separator,
       });
     }
 
@@ -227,7 +225,7 @@ export default class BlockSettings extends Module<BlockSettingsNodes> {
         },
       });
       items.push({
-        type: 'separator',
+        type: PopoverItemType.Separator,
       });
     }
 
@@ -314,28 +312,13 @@ export default class BlockSettings extends Module<BlockSettingsNodes> {
     this.close();
   };
 
-  /**
-   * Returns list of buttons and inputs inside specified container
-   *
-   * @param container - container to query controls inside of
-   */
-  private getControls(container: HTMLElement): HTMLElement[] {
-    const { StylesAPI } = this.Editor;
-    /** Query buttons and inputs inside tunes html */
-    const controls = container.querySelectorAll<HTMLElement>(
-      `.${StylesAPI.classes.settingsButton}, ${$.allInputsSelector}`
-    );
-
-    return Array.from(controls);
-  }
-
   /**
    * Resolves aliases in tunes menu items
    *
    * @param item - item with resolved aliases
    */
   private resolveTuneAliases(item: TunesMenuConfigItem): PopoverItemParams {
-    if (item.type === 'separator') {
+    if (item.type === PopoverItemType.Separator || item.type === PopoverItemType.Html) {
       return item;
     }
     const result = resolveAliases(item, { label: 'title' });

src/components/ui/toolbox.ts

@@ -3,7 +3,7 @@ import { BlockToolAPI } from '../block';
 import Shortcuts from '../utils/shortcuts';
 import BlockTool from '../tools/block';
 import ToolsCollection from '../tools/collection';
-import { API, BlockToolData, ToolboxConfigEntry, PopoverItem, BlockAPI } from '../../../types';
+import { API, BlockToolData, ToolboxConfigEntry, PopoverItemParams, BlockAPI } from '../../../types';
 import EventsDispatcher from '../utils/events';
 import I18n from '../i18n';
 import { I18nInternalNS } from '../i18n/namespace-internal';
@@ -303,11 +303,11 @@ export default class Toolbox extends EventsDispatcher<ToolboxEventMap> {
    * Returns list of items that will be displayed in toolbox
    */
   @_.cacheable
-  private get toolboxItemsToBeDisplayed(): PopoverItem[] {
+  private get toolboxItemsToBeDisplayed(): PopoverItemParams[] {
     /**
      * Maps tool data to popover item structure
      */
-    const toPopoverItem = (toolboxItem: ToolboxConfigEntry, tool: BlockTool): PopoverItem => {
+    const toPopoverItem = (toolboxItem: ToolboxConfigEntry, tool: BlockTool): PopoverItemParams => {
       return {
         icon: toolboxItem.icon,
         title: I18n.t(I18nInternalNS.toolNames, toolboxItem.title || _.capitalize(tool.name)),
@@ -320,7 +320,7 @@ export default class Toolbox extends EventsDispatcher<ToolboxEventMap> {
     };
 
     return this.toolsToBeDisplayed
-      .reduce<PopoverItem[]>((result, tool) => {
+      .reduce<PopoverItemParams[]>((result, tool) => {
         if (Array.isArray(tool.toolbox)) {
           tool.toolbox.forEach(item => {
             result.push(toPopoverItem(item, tool));

src/components/utils/popover/components/popover-item/popover-item-html/popover-item-html.const.ts

@@ -0,0 +1,14 @@
+import { bem } from '../../../../bem';
+
+/**
+ * Popover item block CSS class constructor
+ */
+const className = bem('ce-popover-item-html');
+
+/**
+ * CSS class names to be used in popover item class
+ */
+export const css = {
+  root: className(),
+  hidden: className(null, 'hidden'),
+};

src/components/utils/popover/components/popover-item/popover-item-html/popover-item-html.ts

@@ -0,0 +1,57 @@
+import { PopoverItem } from '../popover-item';
+import { PopoverItemHtmlParams } from '../popover-item.types';
+import { css } from './popover-item-html.const';
+import Dom from '../../../../../dom';
+
+/**
+ * Represents popover item with custom html content
+ */
+export class PopoverItemHtml extends PopoverItem {
+  /**
+   * Item html elements
+   */
+  private nodes: { root: HTMLElement };
+
+  /**
+   * Constructs the instance
+   *
+   * @param params – instance parameters
+   */
+  constructor(params: PopoverItemHtmlParams) {
+    super();
+
+    this.nodes = {
+      root: Dom.make('div', css.root),
+    };
+
+    this.nodes.root.appendChild(params.element);
+  }
+
+  /**
+   * Returns popover item root element
+   */
+  public getElement(): HTMLElement {
+    return this.nodes.root;
+  }
+
+  /**
+   * Toggles item hidden state
+   *
+   * @param isHidden - true if item should be hidden
+   */
+  public toggleHidden(isHidden: boolean): void {
+    this.nodes.root?.classList.toggle(css.hidden, isHidden);
+  }
+
+  /**
+   * Returns list of buttons and inputs inside custom content
+   */
+  public getControls(): HTMLElement[] {
+    /** Query buttons and inputs inside custom html */
+    const controls = this.nodes.root.querySelectorAll<HTMLElement>(
+      `button, ${Dom.allInputsSelector}`
+    );
+
+    return Array.from(controls);
+  }
+}

src/components/utils/popover/components/popover-item/popover-item.types.ts

@@ -1,3 +1,16 @@
+/**
+ * Popover item types
+ */
+export enum PopoverItemType {
+  /** Regular item with icon, title and other properties */
+  Default = 'default',
+
+  /** Gray line used to separate items from each other */
+  Separator = 'separator',
+
+  /** Item with custom html content */
+  Html = 'html'
+}
 
 /**
  * Represents popover item separator.
@@ -7,7 +20,22 @@ export interface PopoverItemSeparatorParams {
   /**
    * Item type
    */
-  type: 'separator'
+  type: PopoverItemType.Separator
+}
+
+/**
+ * Represents popover item with custom html content
+ */
+export interface PopoverItemHtmlParams {
+  /**
+   * Item type
+   */
+  type: PopoverItemType.Html;
+
+  /**
+   * Custom html content to be displayed in the popover
+   */
+  element: HTMLElement
 }
 
 /**
@@ -17,7 +45,7 @@ interface PopoverItemDefaultBaseParams {
   /**
    * Item type
    */
-  type?: 'default';
+  type?: PopoverItemType.Default;
 
   /**
    * Displayed text
@@ -119,5 +147,8 @@ export type PopoverItemDefaultParams =
 /**
  * Represents single popover item
  */
-export type PopoverItemParams = PopoverItemDefaultParams |  PopoverItemSeparatorParams;
+export type PopoverItemParams =
+  PopoverItemDefaultParams |
+  PopoverItemSeparatorParams |
+  PopoverItemHtmlParams;