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

package/src/components/tools/base.ts

@@ -0,0 +1,301 @@
+import type { Tool, ToolConstructable, ToolSettings } from '@/types/tools';
+import type { SanitizerConfig, API as ApiMethods, ToolConfig } from '@/types';
+import { isFunction } from '../utils';
+import { ToolType } from '@/types/tools/adapters/tool-type';
+import type { BaseToolAdapter as BaseToolAdapterInterface } from '@/types/tools/adapters/base-tool-adapter';
+import type { InlineToolAdapter as InlineToolAdapterInterface } from '@/types/tools/adapters/inline-tool-adapter';
+import type { BlockToolAdapter as BlockToolAdapterInterface } from '@/types/tools/adapters/block-tool-adapter';
+import type { BlockTuneAdapter as BlockTuneAdapterInterface } from '@/types/tools/adapters/block-tune-adapter';
+
+/**
+ * Keys that are Blok-level settings (not passed to tool constructor)
+ */
+const BLOK_SETTINGS_KEYS = new Set([
+  'class',
+  'inlineToolbar',
+  'tunes',
+  'shortcut',
+  'toolbox',
+  'config',
+  'isInternal',
+]);
+
+/**
+ * Enum of Tool options provided by user
+ */
+export enum UserSettings {
+  /**
+   * Shortcut for Tool
+   */
+  Shortcut = 'shortcut',
+  /**
+   * Toolbox config for Tool
+   */
+  Toolbox = 'toolbox',
+  /**
+   * Enabled Inline Tools for Block Tool
+   */
+  EnabledInlineTools = 'inlineToolbar',
+  /**
+   * Enabled Block Tunes for Block Tool
+   */
+  EnabledBlockTunes = 'tunes',
+  /**
+   * Tool configuration
+   */
+  Config = 'config',
+}
+
+/**
+ * Enum of Tool options provided by Tool
+ */
+export enum CommonInternalSettings {
+  /**
+   * Shortcut for Tool
+   */
+  Shortcut = 'shortcut',
+  /**
+   * Sanitize configuration for Tool
+   */
+  SanitizeConfig = 'sanitize',
+
+}
+
+/**
+ * Enum of Tool options provided by Block Tool
+ */
+export enum InternalBlockToolSettings {
+  /**
+   * Is line breaks enabled for Tool
+   */
+  IsEnabledLineBreaks = 'enableLineBreaks',
+  /**
+   * Tool Toolbox config
+   */
+  Toolbox = 'toolbox',
+  /**
+   * Tool conversion config
+   */
+  ConversionConfig = 'conversionConfig',
+  /**
+   * Is readonly mode supported for Tool
+   */
+  IsReadOnlySupported = 'isReadOnlySupported',
+  /**
+   * Tool paste config
+   */
+  PasteConfig = 'pasteConfig'
+}
+
+/**
+ * Enum of Tool options provided by Inline Tool
+ */
+export enum InternalInlineToolSettings {
+  /**
+   * Flag specifies Tool is inline
+   */
+  IsInline = 'isInline',
+  /**
+   * Inline Tool title for toolbar
+   */
+  Title = 'title', // for Inline Tools. Block Tools can pass title along with icon through the 'toolbox' static prop.
+
+  /**
+   * Allows inline tool to be available in read-only mode
+   * Can be used, for example, by comments tool
+   */
+  IsReadOnlySupported = 'isReadOnlySupported',
+}
+
+/**
+ * Enum of Tool options provided by Block Tune
+ */
+export enum InternalTuneSettings {
+  /**
+   * Flag specifies Tool is Block Tune
+   */
+  IsTune = 'isTune',
+}
+
+export type ToolOptions = Omit<ToolSettings, 'class'>;
+
+type ToolPreparePayload = {
+  toolName: string;
+  config: ToolConfig;
+};
+
+interface ConstructorOptions {
+  name: string;
+  constructable: ToolConstructable;
+  config: ToolOptions;
+  api: ApiMethods;
+  isDefault: boolean;
+  isInternal: boolean;
+  defaultPlaceholder?: string | false;
+}
+
+/**
+ * Base abstract class for Tools
+ */
+export abstract class BaseToolAdapter<Type extends ToolType = ToolType, ToolClass extends Tool = Tool> implements BaseToolAdapterInterface<ToolType, Tool> {
+  /**
+   * Tool type: Block, Inline or Tune
+   */
+  public abstract type: Type;
+
+  /**
+   * Tool name specified in Blok config
+   */
+  public name: string;
+
+  /**
+   * Flag show is current Tool internal (bundled with Blok core) or not
+   */
+  public readonly isInternal: boolean;
+
+  /**
+   * Flag show is current Tool default or not
+   */
+  public readonly isDefault: boolean;
+
+  /**
+   * Blok API for current Tool
+   */
+  protected api: ApiMethods;
+
+  /**
+   * Current tool user configuration
+   */
+  protected config: ToolOptions;
+
+  /**
+   * Tool's constructable blueprint
+   */
+  protected constructable: ToolConstructable;
+
+  /**
+   * Default placeholder specified in Blok user configuration
+   */
+  protected defaultPlaceholder?: string | false;
+
+  /**
+   * @class
+   * @param {ConstructorOptions} options - Constructor options
+   */
+  constructor({
+    name,
+    constructable,
+    config,
+    api,
+    isDefault,
+    isInternal = false,
+    defaultPlaceholder,
+  }: ConstructorOptions) {
+    this.api = api;
+    this.name = name;
+    this.constructable = constructable;
+    this.config = config;
+    this.isDefault = isDefault;
+    this.isInternal = isInternal;
+    this.defaultPlaceholder = defaultPlaceholder;
+  }
+
+  /**
+   * Returns Tool user configuration.
+   * Extracts tool-specific options from flat config and merges with nested config.
+   */
+  public get settings(): ToolConfig {
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- Internal: reading legacy config for backwards compatibility
+    const nestedConfig = (this.config[UserSettings.Config] ?? {}) as ToolConfig;
+
+    // Extract non-Blok keys as tool-specific config
+    const flatConfig: Record<string, unknown> = {};
+
+    for (const key of Object.keys(this.config)) {
+      if (!BLOK_SETTINGS_KEYS.has(key)) {
+        flatConfig[key] = this.config[key as keyof typeof this.config];
+      }
+    }
+
+    // Merge: nested config first, flat config overrides
+    const config = { ...nestedConfig, ...flatConfig } as ToolConfig;
+
+    if (this.isDefault && !('placeholder' in config) && this.defaultPlaceholder) {
+      config.placeholder = this.defaultPlaceholder;
+    }
+
+    return config;
+  }
+
+  /**
+   * Calls Tool's reset method
+   */
+  public reset(): void | Promise<void> {
+    if (isFunction(this.constructable.reset)) {
+      return this.constructable.reset();
+    }
+  }
+
+  /**
+   * Calls Tool's prepare method
+   */
+  public prepare(): void | Promise<void> {
+    const prepare = this.constructable.prepare;
+
+    if (!isFunction(prepare)) {
+      return;
+    }
+
+    const payload: ToolPreparePayload = {
+      toolName: this.name,
+      config: this.settings,
+    };
+
+    return (prepare as (data: ToolPreparePayload) => void | Promise<void>).call(this.constructable, payload);
+  }
+
+  /**
+   * Returns shortcut for Tool (internal or specified by user)
+   */
+  public get shortcut(): string | undefined {
+    const toolShortcut = this.constructable[CommonInternalSettings.Shortcut];
+    const userShortcut = this.config[UserSettings.Shortcut];
+
+    return userShortcut || toolShortcut;
+  }
+
+  /**
+   * Returns Tool's sanitizer configuration
+   */
+  public get sanitizeConfig(): SanitizerConfig {
+    return this.constructable[CommonInternalSettings.SanitizeConfig] || {};
+  }
+
+  /**
+   * Returns true if Tools is inline
+   */
+  public isInline(): this is InlineToolAdapterInterface {
+    return this.type === ToolType.Inline;
+  }
+
+  /**
+   * Returns true if Tools is block
+   */
+  public isBlock(): this is BlockToolAdapterInterface {
+    return this.type === ToolType.Block;
+  }
+
+  /**
+   * Returns true if Tools is tune
+   */
+  public isTune(): this is BlockTuneAdapterInterface {
+    return this.type === ToolType.Tune;
+  }
+
+  /**
+   * Constructs new Tool instance from constructable blueprint
+   * @param args
+   */
+
+  public abstract create(...args: any[]): ToolClass;
+}

package/src/components/tools/block.ts

@@ -0,0 +1,339 @@
+import { BaseToolAdapter,  InternalBlockToolSettings, UserSettings  } from './base';
+import type {
+  BlockAPI,
+  BlockTool as IBlockTool,
+  BlockToolData,
+  BlockToolConstructable,
+  ConversionConfig,
+  PasteConfig, SanitizerConfig, ToolboxConfig,
+  ToolboxConfigEntry
+} from '@/types';
+import { isEmpty, isObject } from '../utils';
+import type { InlineToolAdapter } from './inline';
+import type { BlockTuneAdapter } from './tune';
+import { ToolsCollection } from './collection';
+import type { BlockToolAdapter as BlockToolAdapterInterface } from '@/types/tools/adapters/block-tool-adapter';
+import { ToolType } from '@/types/tools/adapters/tool-type';
+
+/**
+ * Class to work with Block tools constructables
+ */
+export class BlockToolAdapter extends BaseToolAdapter<ToolType.Block, IBlockTool> implements BlockToolAdapterInterface {
+  /**
+   * Tool type — Block
+   */
+  public type: ToolType.Block = ToolType.Block;
+
+  /**
+   * InlineTool collection for current Block Tool
+   */
+  public inlineTools: ToolsCollection<InlineToolAdapter> = new ToolsCollection<InlineToolAdapter>();
+
+  /**
+   * BlockTune collection for current Block Tool
+   */
+  public tunes: ToolsCollection<BlockTuneAdapter> = new ToolsCollection<BlockTuneAdapter>();
+
+  /**
+   * Cache for sanitize configuration
+   */
+  private _sanitizeConfig: SanitizerConfig | undefined;
+
+  /**
+   * Cache for base sanitize configuration
+   */
+  private _baseSanitizeConfig: SanitizerConfig | undefined;
+
+  /**
+   * Creates new Tool instance
+   * @param data - Tool data
+   * @param block - BlockAPI for current Block
+   * @param readOnly - True if Blok is in read-only mode
+   */
+  public create(data: BlockToolData, block: BlockAPI, readOnly: boolean): IBlockTool {
+    const toolboxEntries = this.toolbox;
+
+    /**
+     * Inject merged toolbox entries into config so tools can use them in renderSettings().
+     * This allows tools like Header to show the same options in block settings as in the toolbox.
+     */
+    const configWithToolbox = toolboxEntries !== undefined
+      ? { ...this.settings, _toolboxEntries: toolboxEntries }
+      : this.settings;
+
+    return new this.constructable({
+      data,
+      block,
+      readOnly,
+      api: this.api,
+      config: configWithToolbox,
+    }) as IBlockTool;
+  }
+
+  /**
+   * Returns true if read-only mode is supported by Tool
+   */
+  public get isReadOnlySupported(): boolean {
+    return (this.constructable as BlockToolConstructable)[InternalBlockToolSettings.IsReadOnlySupported] === true;
+  }
+
+  /**
+   * Returns true if Tool supports linebreaks
+   */
+  public get isLineBreaksEnabled(): boolean {
+    return (this.constructable as unknown as Record<string, boolean | undefined>)[InternalBlockToolSettings.IsEnabledLineBreaks] ?? false;
+  }
+
+  /**
+   * Returns Tool toolbox configuration (internal or user-specified).
+   *
+   * Merges internal and user-defined toolbox configs based on the following rules:
+   *
+   * - If both internal and user-defined toolbox configs are arrays their items are merged.
+   * Length of the second one is kept.
+   *
+   * - If both are objects their properties are merged.
+   *
+   * - If one is an object and another is an array than internal config is replaced with user-defined
+   * config. This is made to allow user to override default tool's toolbox representation (single/multiple entries)
+   *
+   * Additionally, if the tool's config contains a `toolboxStyles` array, only toolbox entries
+   * whose `data.style` matches one of the specified styles will be included.
+   */
+  public get toolbox(): ToolboxConfigEntry[] | undefined {
+    const toolToolboxSettings = (this.constructable as BlockToolConstructable)[InternalBlockToolSettings.Toolbox] as ToolboxConfig | undefined;
+    const userToolboxSettings = this.config[UserSettings.Toolbox];
+
+    if (!toolToolboxSettings || isEmpty(toolToolboxSettings)) {
+      return;
+    }
+    if (userToolboxSettings === false) {
+      return;
+    }
+
+    const mergedEntries = this.mergeToolboxSettings(toolToolboxSettings, userToolboxSettings);
+    const filteredByStyles = this.filterToolboxEntriesByStyles(mergedEntries);
+
+    return this.filterToolboxEntriesByLevels(filteredByStyles);
+  }
+
+  /**
+   * Merges tool's internal toolbox settings with user-defined settings
+   */
+  private mergeToolboxSettings(
+    toolSettings: ToolboxConfig,
+    userSettings: ToolboxConfig | undefined | null
+  ): ToolboxConfigEntry[] {
+    /**
+     * Return tool's toolbox settings if user settings are not defined
+     */
+    if (userSettings === undefined || userSettings === null) {
+      return Array.isArray(toolSettings) ? toolSettings : [ toolSettings ];
+    }
+
+    /**
+     * User provided single entry to override array of tool entries
+     */
+    if (!Array.isArray(userSettings) && Array.isArray(toolSettings)) {
+      return [ userSettings ];
+    }
+
+    /**
+     * Both are single entries - merge them
+     */
+    if (!Array.isArray(userSettings)) {
+      return [
+        {
+          ...toolSettings,
+          ...userSettings,
+        },
+      ];
+    }
+
+    /**
+     * User provided array but tool has single entry
+     */
+    if (!Array.isArray(toolSettings)) {
+      return userSettings;
+    }
+
+    /**
+     * Both are arrays - merge item by item
+     */
+    return userSettings.map((item, i) => {
+      const toolToolboxEntry = toolSettings[i];
+
+      if (toolToolboxEntry) {
+        return {
+          ...toolToolboxEntry,
+          ...item,
+        };
+      }
+
+      return item;
+    });
+  }
+
+  /**
+   * Filters toolbox entries based on toolboxStyles config if specified.
+   * This allows tools like List to show only specific variants in the toolbox.
+   */
+  private filterToolboxEntriesByStyles(entries: ToolboxConfigEntry[]): ToolboxConfigEntry[] {
+    const toolboxStyles = this.settings.toolboxStyles as string[] | undefined;
+
+    if (!toolboxStyles || !Array.isArray(toolboxStyles) || toolboxStyles.length === 0) {
+      return entries;
+    }
+
+    return entries.filter(entry => {
+      const entryData = entry.data as { style?: string } | undefined;
+
+      if (!entryData || !entryData.style) {
+        return true; // Keep entries without style data
+      }
+
+      return toolboxStyles.includes(entryData.style);
+    });
+  }
+
+  /**
+   * Filters toolbox entries based on levels config if specified.
+   * This allows tools like Header to show only configured heading levels in the toolbox.
+   */
+  private filterToolboxEntriesByLevels(entries: ToolboxConfigEntry[]): ToolboxConfigEntry[] {
+    const levels = this.settings.levels as number[] | undefined;
+
+    if (!levels || !Array.isArray(levels) || levels.length === 0) {
+      return entries;
+    }
+
+    return entries.filter(entry => {
+      const entryData = entry.data as { level?: number } | undefined;
+
+      if (!entryData || entryData.level === undefined) {
+        return true; // Keep entries without level data
+      }
+
+      return levels.includes(entryData.level);
+    });
+  }
+
+  /**
+   * Returns Tool conversion configuration
+   */
+  public get conversionConfig(): ConversionConfig | undefined {
+    return (this.constructable as BlockToolConstructable)[InternalBlockToolSettings.ConversionConfig];
+  }
+
+  /**
+   * Returns enabled inline tools for Tool.
+   * Defaults to true (all inline tools) unless explicitly set to false or array.
+   */
+  public get enabledInlineTools(): boolean | string[] {
+    const setting = this.config[UserSettings.EnabledInlineTools];
+
+    // Default to true if not specified
+    if (setting === undefined) {
+      return true;
+    }
+
+    return setting;
+  }
+
+  /**
+   * Returns enabled tunes for Tool
+   */
+  public get enabledBlockTunes(): boolean | string[] | undefined {
+    return this.config[UserSettings.EnabledBlockTunes];
+  }
+
+  /**
+   * User-provided search terms from tool settings.
+   * These are merged with library-defined searchTerms in the toolbox config.
+   */
+  public get searchTerms(): string[] | undefined {
+    return this.settings.searchTerms;
+  }
+
+  /**
+   * Returns Tool paste configuration
+   */
+  public get pasteConfig(): PasteConfig {
+    return (this.constructable as BlockToolConstructable)[InternalBlockToolSettings.PasteConfig] ?? {};
+  }
+
+  /**
+   * Returns true if Tool has onPaste handler
+   */
+  public get hasOnPasteHandler(): boolean {
+    const prototype = (this.constructable as unknown as { prototype?: { onPaste?: unknown } })?.prototype;
+
+    return typeof prototype?.onPaste === 'function';
+  }
+
+  /**
+   * Returns sanitize configuration for Block Tool including configs from related Inline Tools and Block Tunes
+   */
+  public get sanitizeConfig(): SanitizerConfig {
+    if (this._sanitizeConfig) {
+      return this._sanitizeConfig;
+    }
+
+    const toolRules = super.sanitizeConfig;
+    const baseConfig = this.baseSanitizeConfig;
+
+    if (isEmpty(toolRules)) {
+      this._sanitizeConfig = baseConfig;
+
+      return baseConfig;
+    }
+
+    const toolConfig = {} as SanitizerConfig;
+
+    for (const fieldName in toolRules) {
+      if (!Object.prototype.hasOwnProperty.call(toolRules, fieldName)) {
+        continue;
+      }
+
+      const rule = toolRules[fieldName];
+
+      /**
+       * If rule is object, merge it with Inline Tools configuration
+       *
+       * Otherwise pass as it is
+       */
+      if (isObject(rule)) {
+        toolConfig[fieldName] = Object.assign({}, baseConfig, rule);
+      } else {
+        toolConfig[fieldName] = rule;
+      }
+    }
+
+    this._sanitizeConfig = toolConfig;
+
+    return toolConfig;
+  }
+
+  /**
+   * Returns sanitizer configuration composed from sanitize config of Inline Tools enabled for Tool
+   */
+  public get baseSanitizeConfig(): SanitizerConfig {
+    if (this._baseSanitizeConfig) {
+      return this._baseSanitizeConfig;
+    }
+
+    const baseConfig = {};
+
+    Array
+      .from(this.inlineTools.values())
+      .forEach(tool => Object.assign(baseConfig, tool.sanitizeConfig));
+
+    Array
+      .from(this.tunes.values())
+      .forEach(tune => Object.assign(baseConfig, tune.sanitizeConfig));
+
+    this._baseSanitizeConfig = baseConfig;
+
+    return baseConfig;
+  }
+}

package/src/components/tools/collection.ts

@@ -0,0 +1,67 @@
+import type { BlockToolAdapter } from './block';
+import type { InlineToolAdapter } from './inline';
+import type { BlockTuneAdapter } from './tune';
+import type { ToolsCollection as ToolsCollectionInterface } from '@/types/tools/adapters/tools-collection';
+
+
+export type ToolClass = BlockToolAdapter | InlineToolAdapter | BlockTuneAdapter;
+
+/**
+ * Class to store Blok Tools
+ */
+export class ToolsCollection<V extends ToolClass = ToolClass> extends Map<string, V> implements ToolsCollectionInterface<V> {
+  /**
+   * Returns Block Tools collection
+   */
+  public get blockTools(): ToolsCollection<BlockToolAdapter> {
+    const tools = Array
+      .from(this.entries())
+      .filter(([, tool]) => tool.isBlock()) as [string, BlockToolAdapter][];
+
+    return new ToolsCollection<BlockToolAdapter>(tools);
+  }
+
+  /**
+   * Returns Inline Tools collection
+   */
+  public get inlineTools(): ToolsCollection<InlineToolAdapter> {
+    const tools = Array
+      .from(this.entries())
+      .filter(([, tool]) => tool.isInline()) as [string, InlineToolAdapter][];
+
+    return new ToolsCollection<InlineToolAdapter>(tools);
+  }
+
+  /**
+   * Returns Block Tunes collection
+   */
+  public get blockTunes(): ToolsCollection<BlockTuneAdapter> {
+    const tools = Array
+      .from(this.entries())
+      .filter(([, tool]) => tool.isTune()) as [string, BlockTuneAdapter][];
+
+    return new ToolsCollection<BlockTuneAdapter>(tools);
+  }
+
+  /**
+   * Returns internal Tools collection
+   */
+  public get internalTools(): ToolsCollection<V> {
+    const tools = Array
+      .from(this.entries())
+      .filter(([, tool]) => tool.isInternal);
+
+    return new ToolsCollection<V>(tools);
+  }
+
+  /**
+   * Returns Tools collection provided by user
+   */
+  public get externalTools(): ToolsCollection<V> {
+    const tools = Array
+      .from(this.entries())
+      .filter(([, tool]) => !tool.isInternal);
+
+    return new ToolsCollection<V>(tools);
+  }
+}