@jackuait/blok 0.4.3-beta.1 → 0.4.3-beta.10

package/src/components/tools/factory.ts

@@ -5,6 +5,7 @@ import { BlockTuneAdapter } from './tune';
 import { BlockToolAdapter } from './block';
 import type { API as ApiModule } from '../modules/api';
 import type { BlokConfig } from '../../../types/configs';
+import type { API as ApiMethods, I18n } from '../../../types';
 
 type ToolConstructor = typeof InlineToolAdapter | typeof BlockToolAdapter | typeof BlockTuneAdapter;
 
@@ -56,18 +57,66 @@ export class ToolsFactory {
     }
 
     const Constructor = this.getConstructor(constructable);
+    const toolApi = this.createToolApi(name);
 
     return new Constructor({
       name,
       constructable,
       config,
-      api: this.api.methods,
+      api: toolApi,
       isDefault: name === this.blokConfig.defaultBlock,
       defaultPlaceholder: this.blokConfig.placeholder,
       isInternal,
     });
   }
 
+  /**
+   * Creates a tool-specific API with namespaced i18n.
+   *
+   * EditorJS tools expect `api.i18n.t('key')` to automatically look up
+   * `tools.{toolName}.key`. This wrapper provides that behavior while
+   * falling back to direct key lookup for Blok internal tools that use
+   * fully-qualified keys like `tools.stub.error`.
+   *
+   * @param toolName - Name of the tool
+   * @returns API object with tool-namespaced i18n
+   */
+  private createToolApi(toolName: string): ApiMethods {
+    const baseApi = this.api.methods;
+    const namespace = `tools.${toolName}`;
+
+    const namespacedI18n: I18n = {
+      t: (dictKey: string): string => {
+        /**
+         * Try namespaced key first for EditorJS compatibility.
+         * External tools call t('Add row') expecting lookup of 'tools.table.Add row'.
+         */
+        const namespacedKey = `${namespace}.${dictKey}`;
+
+        if (baseApi.i18n.has(namespacedKey)) {
+          return baseApi.i18n.t(namespacedKey);
+        }
+
+        /**
+         * Fall back to direct key lookup for Blok internal tools.
+         * Internal tools use fully-qualified keys like 'tools.stub.error'.
+         */
+        return baseApi.i18n.t(dictKey);
+      },
+
+      has: (dictKey: string): boolean => {
+        const namespacedKey = `${namespace}.${dictKey}`;
+
+        return baseApi.i18n.has(namespacedKey) || baseApi.i18n.has(dictKey);
+      },
+    };
+
+    return {
+      ...baseApi,
+      i18n: namespacedI18n,
+    };
+  }
+
   /**
    * Find appropriate Tool object constructor for Tool constructable
    * @param constructable - Tools constructable

package/src/components/utils/tooltip.ts

@@ -583,20 +583,6 @@ class Tooltip {
     }
   }
 
-  /**
-   * Append element or a couple to the beginning of the parent elements
-   * @param {Element} parent - where to append
-   * @param {Element|Element[]} elements - element or elements list
-   */
-  private prepend(parent: Element, elements: Element | Element[]): void {
-    if (Array.isArray(elements)) {
-      const reversed = elements.reverse();
-
-      reversed.forEach((el) => parent.prepend(el));
-    } else {
-      parent.prepend(elements);
-    }
-  }
 }
 
 /**

package/src/tools/header/index.ts

@@ -16,6 +16,7 @@ import type {
   BlockToolData,
   PasteEvent,
   ToolboxConfig,
+  ToolboxConfigEntry,
   ConversionConfig,
   SanitizerConfig,
   PasteConfig,
@@ -60,6 +61,11 @@ export interface HeaderConfig {
   defaultLevel?: number;
   /** Level-specific overrides keyed by level number (1-6) */
   levelOverrides?: Record<number, HeaderLevelConfig>;
+  /**
+   * @internal Injected by BlockToolAdapter - merged toolbox entries.
+   * When present, renderSettings() will use these entries instead of the default levels.
+   */
+  _toolboxEntries?: ToolboxConfigEntry[];
 }
 
 /**
@@ -195,6 +201,28 @@ export class Header implements BlockTool {
    * @returns MenuConfig array
    */
   public renderSettings(): MenuConfig {
+    const toolboxEntries = this._settings._toolboxEntries;
+
+    /**
+     * If user provided custom toolbox entries, use them to build settings menu.
+     * This ensures block settings match the toolbox configuration.
+     * Entries without explicit level data will default to the configured defaultLevel.
+     *
+     * Only fall back to levels config when _toolboxEntries is not provided or empty,
+     * or when using the default single "Heading" toolbox entry (detected by having
+     * exactly one entry with no level data and no custom title or the default "Heading" title).
+     */
+    const isDefaultToolboxEntry = toolboxEntries?.length === 1 &&
+      toolboxEntries[0].data === undefined &&
+      (toolboxEntries[0].title === undefined || toolboxEntries[0].title === 'Heading');
+
+    if (toolboxEntries !== undefined && toolboxEntries.length > 0 && !isDefaultToolboxEntry) {
+      return this.buildSettingsFromToolboxEntries(toolboxEntries);
+    }
+
+    /**
+     * Fall back to existing behavior using levels config
+     */
     return this.levels.map(level => {
       const translated = this.api.i18n.t(level.nameKey);
       const title = translated !== level.nameKey ? translated : level.name;
@@ -212,6 +240,60 @@ export class Header implements BlockTool {
     });
   }
 
+  /**
+   * Build settings menu items from toolbox entries.
+   * This allows users to customize which levels appear in block settings
+   * by configuring the toolbox.
+   *
+   * @param entries - Merged toolbox entries from user config
+   * @returns MenuConfig array
+   */
+  private buildSettingsFromToolboxEntries(entries: ToolboxConfigEntry[]): MenuConfig {
+    return entries.map(entry => {
+      const entryData = entry.data as { level?: number } | undefined;
+      const level = entryData?.level ?? this.defaultLevel.number;
+      const defaultLevel = Header.DEFAULT_LEVELS.find(l => l.number === level);
+      const fallbackTitle = defaultLevel?.name ?? `Heading ${level}`;
+
+      const title = this.resolveToolboxEntryTitle(entry, fallbackTitle);
+      const icon = entry.icon ?? defaultLevel?.icon ?? IconHeading;
+
+      return {
+        icon,
+        title,
+        onActivate: (): void => this.setLevel(level),
+        closeOnActivate: true,
+        isActive: this.currentLevel.number === level,
+        dataset: {
+          'blok-header-level': String(level),
+        },
+      };
+    });
+  }
+
+  /**
+   * Resolves the title for a toolbox entry.
+   * Priority: custom title > i18n key translation > fallback
+   *
+   * @param entry - Toolbox entry
+   * @param fallback - Fallback title if no custom title or translation found
+   * @returns Resolved title string
+   */
+  private resolveToolboxEntryTitle(entry: ToolboxConfigEntry, fallback: string): string {
+    if (entry.title !== undefined) {
+      return entry.title;
+    }
+
+    if (entry.titleKey === undefined) {
+      return fallback;
+    }
+
+    const namespacedKey = `toolNames.${entry.titleKey}`;
+    const translated = this.api.i18n.t(namespacedKey);
+
+    return translated !== namespacedKey ? translated : fallback;
+  }
+
   /**
    * Callback for Block's settings buttons
    *

package/src/tools/index.ts

@@ -6,10 +6,16 @@
  * // Import specific tools
  * import { Paragraph, Header, List, Bold, Italic, Link } from '@jackuait/blok/tools';
  *
- * // Use in Blok configuration
+ * // Use in Blok configuration (flat config style)
  * new Blok({
- *   tools: { paragraph: Paragraph, header: Header, list: List },
- *   inlineTools: { bold: Bold, italic: Italic, link: Link }
+ *   tools: {
+ *     paragraph: Paragraph,
+ *     header: { class: Header, levels: [1, 2, 3] },
+ *     list: List,
+ *     bold: Bold,
+ *     italic: Italic,
+ *     link: Link,
+ *   }
  * });
  */
 
@@ -25,10 +31,11 @@ export { LinkInlineTool as Link } from '../components/inline-tools/inline-tool-l
 export { ConvertInlineTool as Convert } from '../components/inline-tools/inline-tool-convert';
 
 // Default tools configuration for convenience
+// Note: inlineToolbar defaults to true, so it doesn't need to be specified
 export const defaultBlockTools = {
-  paragraph: { inlineToolbar: true, config: { preserveBlank: true } },
-  header: { inlineToolbar: true },
-  list: { inlineToolbar: true },
+  paragraph: { preserveBlank: true },
+  header: {},
+  list: {},
 } as const;
 
 export const defaultInlineTools = {

package/src/tools/list/index.ts

@@ -226,10 +226,10 @@ export class ListItem implements BlockTool {
     return this._settings.itemSize;
   }
 
-  private static readonly DEFAULT_PLACEHOLDER = 'List';
+  private static readonly PLACEHOLDER_KEY = 'tools.list.placeholder';
 
   private get placeholder(): string {
-    return this.api.i18n.t(ListItem.DEFAULT_PLACEHOLDER);
+    return this.api.i18n.t(ListItem.PLACEHOLDER_KEY);
   }
 
   private applyItemStyles(element: HTMLElement): void {

package/types/api/i18n.d.ts

@@ -10,4 +10,12 @@ export interface I18n {
    * @returns Translated string, or the key itself if translation is missing
    */
   t(dictKey: string): string;
+
+  /**
+   * Check if a translation exists for the given key.
+   *
+   * @param dictKey - Full translation key to check
+   * @returns True if translation exists, false otherwise
+   */
+  has(dictKey: string): boolean;
 }

package/types/tools/tool-settings.d.ts

@@ -1,6 +1,12 @@
 import { ToolConfig } from './tool-config';
 import { ToolConstructable, BlockToolData, MenuConfig, MenuConfigItem } from './index';
 
+/**
+ * Permissive type for tool class - accepts any constructor.
+ * Runtime validation ensures the tool has required methods.
+ */
+export type ToolClass = new (...args: any[]) => any;
+
 /**
  * Tool may specify its toolbox configuration
  * It may include several entries as well
@@ -49,9 +55,9 @@ export interface ToolboxConfigEntry {
 export interface ExternalToolSettings<Config extends object = any> {
 
   /**
-   * Tool's class
+   * Tool's class - accepts any constructor, validated at runtime
    */
-  class: ToolConstructable;
+  class: ToolConstructable | ToolClass;
 
   /**
    * User configuration object that will be passed to the Tool's constructor
@@ -88,6 +94,58 @@ export interface ExternalToolSettings<Config extends object = any> {
 export type InternalToolSettings<Config extends object = any> = Omit<ExternalToolSettings<Config>, 'class'> & Partial<Pick<ExternalToolSettings<Config>, 'class'>>;
 
 /**
- * Union of external and internal Tools settings
+ * Keys that Blok extracts from tool settings (not passed to tool constructor)
+ */
+export type BlokToolSettingsKeys = 'class' | 'inlineToolbar' | 'tunes' | 'shortcut' | 'toolbox' | 'config';
+
+/**
+ * Flat tool settings - tool-specific options at top level.
+ * Blok extracts known keys and passes the rest as `config` to the tool.
+ */
+export interface FlatToolSettings<Config extends object = any> {
+  /**
+   * Tool's class
+   */
+  class: ToolConstructable | ToolClass;
+
+  /**
+   * Is need to show Inline Toolbar.
+   * Defaults to true for block tools.
+   */
+  inlineToolbar?: boolean | string[];
+
+  /**
+   * BlockTunes for Tool
+   */
+  tunes?: boolean | string[];
+
+  /**
+   * Define shortcut that will render Tool
+   */
+  shortcut?: string;
+
+  /**
+   * Tool's Toolbox settings
+   */
+  toolbox?: ToolboxConfig | false;
+
+  /**
+   * Legacy nested config - merged with top-level tool options
+   * @deprecated Use flat config instead
+   */
+  config?: ToolConfig<Config>;
+
+  /**
+   * Tool-specific options (placeholder, levels, etc.)
+   * These are passed to the tool constructor as `config`
+   */
+  [key: string]: unknown;
+}
+
+/**
+ * Union of all tool settings formats
  */
-export type ToolSettings<Config extends object = any> = InternalToolSettings<Config> | ExternalToolSettings<Config>;
+export type ToolSettings<Config extends object = any> =
+  | InternalToolSettings<Config>
+  | ExternalToolSettings<Config>
+  | FlatToolSettings<Config>;