Tools options (#134)

* Fix inputs and values attachments to be data-first

* Load adapters as plugin

* Fix tests

* Review comments

* (try to) fix test run for core package

* Run base branch coverage manually

* Fix unit-tests action: use ArtiomTr with pre-generated coverage files

* Try just PR branch tests

* Try clear before build

* Try no cache

* Use latest node

* Review comments resolved

* Resolve review comments

* Add destoryBlockToolAdapter method to Adapter plugin

* Block ID implementation

* Fix lint

* Fix tests

* Fix build

* Remove userId from getBlockSerialized method

* Fix call in the block manager

* Move all tool's static configuration properties to the single options property

* review comments

* Review comments

Author: gohabereg

packages/core/src/index.ts

@@ -7,9 +7,9 @@ import {
   EventBus,
   type InlineToolConstructor,
   PluginType,
-  ToolType
+  ToolType,
+  type ToolStaticOptions
 } from '@editorjs/sdk';
-import type { ToolSettings } from './tools/ToolsFactory';
 import { composeDataFromVersion2 } from './utils/composeDataFromVersion2.js';
 import ToolsManager from './tools/ToolsManager.js';
 import type { CoreConfigValidated, CoreConfig, EditorjsPluginConstructor, BlockTuneConstructor, ToolConstructable, EditorjsAdapterPluginConstructor } from '@editorjs/sdk';
@@ -126,9 +126,9 @@ export default class Core {
   /**
    * Injects Tool constructor and options into the container
    * @param tool - Tool constructor class (static `options` defines defaults merged with the second argument)
-   * @param options - feature flags, `config` for the tool plugin, etc.
+   * @param options - Overrides for the tool's static `options` (toolbox, title, config, shortcuts, etc.)
    */
-  public use(tool: ToolConstructable, options?: Omit<ToolSettings, 'class'>): Core;
+  public use(tool: ToolConstructable, options?: ToolStaticOptions): Core;
   /**
    * Injects Plugin into the container to initialize on Editor's init
    * @param plugin - allows to pass any implementation of editor plugins
@@ -141,15 +141,15 @@ export default class Core {
    */
   public use(
     pluginOrTool: ToolConstructable | EditorjsPluginConstructor | EditorjsAdapterPluginConstructor,
-    options?: Omit<ToolSettings, 'class'>
+    options?: ToolStaticOptions
   ): Core {
     const pluginType = pluginOrTool.type;
 
     switch (pluginType) {
       case ToolType.Block:
       case ToolType.Inline:
       case ToolType.Tune:
-        this.#plugins.bind<[ToolConstructable, ToolSettings | undefined]>(pluginType).toConstantValue([pluginOrTool as ToolConstructable, options as ToolSettings | undefined]);
+        this.#plugins.bind<[ToolConstructable, ToolStaticOptions | undefined]>(pluginType).toConstantValue([pluginOrTool as ToolConstructable, options]);
         break;
       case PluginType.Adapter:
         if (this.#plugins.isBound(PluginType.Adapter)) {
@@ -193,9 +193,9 @@ export default class Core {
    * Initalizes loaded tools
    */
   async #initializeTools(): Promise<void> {
-    const blockTools = this.#plugins.getAll<[BlockToolConstructor, ToolSettings]>(ToolType.Block);
-    const inlineTools = this.#plugins.getAll<[InlineToolConstructor, ToolSettings]>(ToolType.Inline);
-    const blockTunes = this.#plugins.getAll<[BlockTuneConstructor, ToolSettings]>(ToolType.Tune);
+    const blockTools = this.#plugins.getAll<[BlockToolConstructor, ToolStaticOptions | undefined]>(ToolType.Block);
+    const inlineTools = this.#plugins.getAll<[InlineToolConstructor, ToolStaticOptions | undefined]>(ToolType.Inline);
+    const blockTunes = this.#plugins.getAll<[BlockTuneConstructor, ToolStaticOptions | undefined]>(ToolType.Tune);
 
     return this.#toolsManager.prepareTools([...blockTools, ...inlineTools, ...blockTunes]);
   }

packages/core/src/tools/ToolsFactory.ts

@@ -1,25 +1,24 @@
 /* eslint-disable jsdoc/informative-docs */
 import type { EditorAPI } from '@editorjs/sdk';
 import { ToolType } from '@editorjs/sdk';
-import type { ToolConstructable } from '@editorjs/sdk';
+import type { ToolConstructable, ToolStaticOptions } from '@editorjs/sdk';
 import {
   InlineToolFacade,
   BlockTuneFacade,
   BlockToolFacade
 } from '@editorjs/sdk';
 import type {
-  EditorConfig,
-  ToolSettings as ToolSettingsV2
+  EditorConfig
 } from '@editorjs/editorjs';
 
 type ToolConstructor = typeof InlineToolFacade | typeof BlockToolFacade | typeof BlockTuneFacade;
 
 /**
- * Need this utility type to override some V2 options
+ * Full tool registration entry: the constructor class plus its options.
  */
-export type ToolSettings = Omit<ToolSettingsV2, 'constructable' | 'class'> & {
+export type ToolSettings = ToolStaticOptions & {
   /**
-   * Redefine constructable to match V3
+   * Tool's constructor
    */
   class: ToolConstructable;
 };
@@ -70,10 +69,10 @@ export class ToolsFactory {
    * Register tools in the factory
    * @param tools - tools to register in the factory
    */
-  public setTools(tools: [ToolConstructable, ToolSettings][]): void {
+  public setTools(tools: [ToolConstructable, ToolStaticOptions | undefined][]): void {
     tools.forEach(([tool, settings]) => {
       this.#toolsSettings.set(tool.name, {
-        ...settings,
+        ...(settings ?? {}),
         class: tool,
       });
     });

packages/core/src/tools/ToolsManager.ts

@@ -14,7 +14,8 @@ import {
   ToolFacadeClass,
   ToolsCollection,
   EventBus,
-  ToolConstructable
+  type ToolConstructable,
+  type ToolStaticOptions
 } from '@editorjs/sdk';
 
 /**
@@ -105,7 +106,7 @@ export default class ToolsManager {
    * Calls tools prepare method if it exists and adds tools to relevant collection (available or unavailable tools)
    * @param tools - tools to prepare and their settings
    */
-  public async prepareTools(tools: [ToolConstructable, ToolSettings][]): Promise<void> {
+  public async prepareTools(tools: [ToolConstructable, ToolStaticOptions | undefined][]): Promise<void> {
     const promiseQueue = new PromiseQueue();
 
     const setToAvailableToolsCollection = (toolName: string, tool: ToolFacadeClass): void => {

packages/core/src/tools/internal/inline-tools/bold/index.ts

@@ -19,12 +19,19 @@ export class BoldInlineTool implements InlineTool {
    */
   public static type = ToolType.Inline as const;
 
-  public static title = 'Bold';
+  /**
+   * Tool name used to identify the tool across the editor.
+   */
+  public static name = 'bold';
 
   /**
    * Predefined options (can be overriden on connection)
    */
   public static readonly options = {
+    /**
+     * Tool title shown in the inline toolbar
+     */
+    title: 'Bold',
     /**
      * Shortcuts plugin options
      */

packages/core/src/tools/internal/inline-tools/italic/index.ts

@@ -19,12 +19,19 @@ export class ItalicInlineTool implements InlineTool {
    */
   public static type = ToolType.Inline as const;
 
-  public static title = 'Italic';
+  /**
+   * Tool name used to identify the tool across the editor.
+   */
+  public static name = 'italic';
 
   /**
    * Default options (merged with second argument of `use(ItalicInlineTool, options)`).
    */
   public static readonly options = {
+    /**
+     * Tool title shown in the inline toolbar
+     */
+    title: 'Italic',
     /**
      * Shortcuts plugin options
      */

packages/core/src/tools/internal/inline-tools/link/index.ts

@@ -26,7 +26,20 @@ export class LinkInlineTool implements InlineTool {
    */
   public static type = ToolType.Inline as const;
 
-  public static title = 'Link';
+  /**
+   * Tool name used to identify the tool across the editor.
+   */
+  public static name = 'link';
+
+  /**
+   * Default options (merged with second argument of `use(LinkInlineTool, options)`).
+   */
+  public static readonly options = {
+    /**
+     * Tool title shown in the inline toolbar
+     */
+    title: 'Link',
+  };
 
   /**
    * Type of behaviour of the tool if new selection range intersect with existing fragment

packages/sdk/src/entities/BaseTool.ts

@@ -1,35 +1,96 @@
 import type { ToolConfig } from '@editorjs/editorjs';
+import type { BlockToolOptions } from './BlockTool.js';
+import type { InlineToolOptions } from './InlineTool.js';
+import type { BlockTuneOptions } from './BlockTune.js';
+import type { ToolType } from './EntityType.js';
 
 /**
- * Common interface for Tools static properties
+ * Canonical keys shared by every tool options interface.
  */
-export interface BaseToolConstructor<Config extends ToolConfig = ToolConfig> {
+export enum BaseToolOptionKey {
   /**
-   * Default tool options (`static get options()`) provided by the tool developer.
+   * Plugin-specific configuration object passed to the tool instance.
    */
-  options?: {
-    /**
-     * Internal tool configuration
-     */
-    config?: Record<string, unknown>;
+  Config = 'config'
+}
+
+/**
+ * Options common to every tool type.
+ * @template Config - Shape of the plugin-specific {@link BaseToolOptionKey.Config} object.
+ */
+export interface BaseToolOptions<Config extends ToolConfig = ToolConfig> {
+  /**
+   * Plugin-specific configuration passed to the tool instance.
+   * Defaults set here are merged with (and overridden by) the `config` key
+   * in the second argument of `core.use(Tool, options)`.
+   */
+  [BaseToolOptionKey.Config]?: Config;
+}
 
-    /**
-     * Other tool options
-     */
-    [key: string]: unknown;
-  };
+// Re-export so consumers can import all option types from this file
+export type { BlockToolOptions, InlineToolOptions, BlockTuneOptions };
+
+/**
+ * Union of all per-tool option shapes.
+ * Used as the type of the second argument of `core.use(Tool, options)`.
+ */
+export type ToolStaticOptions = BlockToolOptions | InlineToolOptions | BlockTuneOptions;
+
+/**
+ * Maps a {@link ToolType} value to its corresponding tool options interface.
+ * @example
+ * function getTitle<T extends ToolType>(type: T, options: ToolTypeToOptions[T]) { ... }
+ */
+export type ToolTypeToOptions = {
+  /**
+   * BlockTool Options
+   */
+  [ToolType.Block]: BlockToolOptions;
+  /**
+   * InlineTool Options
+   */
+  [ToolType.Inline]: InlineToolOptions;
+  /**
+   * BlockTune Options
+   */
+  [ToolType.Tune]: BlockTuneOptions;
+};
+
+/**
+ * Common interface for Tool constructor (static) side.
+ * @template Config  - Shape of the plugin-specific config object. Passed to
+ *                     {@link prepare} and used to type {@link options.config}.
+ * @template Options - The concrete options interface for this tool type
+ *                     (defaults to the generic {@link BaseToolOptions}).
+ */
+export interface BaseToolConstructor<
+  Config extends ToolConfig = ToolConfig,
+  Options extends BaseToolOptions<Config> = BaseToolOptions<Config>
+> {
+  /**
+   * Tool name used to identify the tool across the editor.
+   * Falls back to the JavaScript class name if not explicitly set.
+   */
+  name: string;
+
+  /**
+   * All static configuration for the tool.
+   * Values here are defaults; they can be overridden via the second argument
+   * of `core.use(Tool, options)`.
+   */
+  options?: Options;
 
   /**
-   * Tool's prepare method. Can be async
+   * Tool's prepare method. Can be async.
    * @param data - Object with toolName and config properties
    * @param data.toolName - Tool's own name
-   * @param data.config - Tool's configuration
+   * @param data.config   - Merged plugin configuration
    */
   // eslint-disable-next-line -- ESLint doesn't understand it's a type
   prepare?(data: { toolName: string, config: Config }): void | Promise<void>;
 
   /**
-   * Tool's reset method to clean up anything set by prepare. Can be async
+   * Tool's reset method to clean up anything set by prepare. Can be async.
    */
   reset?(): void | Promise<void>;
 }