@jackuait/blok 0.4.1 → 0.4.2

package/src/components/utils/shortcut.ts

@@ -0,0 +1,231 @@
+/**
+ * Supported modifier commands and their aliases
+ */
+const SUPPORTED_COMMANDS = {
+  SHIFT: ['SHIFT'],
+  CMD: ['CMD', 'CONTROL', 'COMMAND', 'WINDOWS', 'CTRL'],
+  ALT: ['ALT', 'OPTION'],
+} as const;
+
+/**
+ * Key name mappings to event.code values
+ */
+const KEY_CODES: Record<string, string> = {
+  '0': 'Digit0',
+  '1': 'Digit1',
+  '2': 'Digit2',
+  '3': 'Digit3',
+  '4': 'Digit4',
+  '5': 'Digit5',
+  '6': 'Digit6',
+  '7': 'Digit7',
+  '8': 'Digit8',
+  '9': 'Digit9',
+  'A': 'KeyA',
+  'B': 'KeyB',
+  'C': 'KeyC',
+  'D': 'KeyD',
+  'E': 'KeyE',
+  'F': 'KeyF',
+  'G': 'KeyG',
+  'H': 'KeyH',
+  'I': 'KeyI',
+  'J': 'KeyJ',
+  'K': 'KeyK',
+  'L': 'KeyL',
+  'M': 'KeyM',
+  'N': 'KeyN',
+  'O': 'KeyO',
+  'P': 'KeyP',
+  'Q': 'KeyQ',
+  'R': 'KeyR',
+  'S': 'KeyS',
+  'T': 'KeyT',
+  'U': 'KeyU',
+  'V': 'KeyV',
+  'W': 'KeyW',
+  'X': 'KeyX',
+  'Y': 'KeyY',
+  'Z': 'KeyZ',
+  'BACKSPACE': 'Backspace',
+  'ENTER': 'Enter',
+  'ESCAPE': 'Escape',
+  'LEFT': 'ArrowLeft',
+  'UP': 'ArrowUp',
+  'RIGHT': 'ArrowRight',
+  'DOWN': 'ArrowDown',
+  'INSERT': 'Insert',
+  'DELETE': 'Delete',
+  '.': 'Period',
+};
+
+type ModifierKey = keyof typeof SUPPORTED_COMMANDS;
+
+/**
+ * Finds the modifier key that matches the given alias
+ * @param alias - The alias to check (e.g., 'CMD', 'CTRL', 'OPTION')
+ * @returns The modifier key if found, undefined otherwise
+ */
+const findModifierKey = (alias: string): ModifierKey | undefined => {
+  const modifierKeys = Object.keys(SUPPORTED_COMMANDS) as ModifierKey[];
+
+  return modifierKeys.find((command) =>
+    SUPPORTED_COMMANDS[command].includes(alias as never)
+  );
+};
+
+/**
+ * Options for creating a keyboard shortcut
+ */
+export interface ShortcutOptions {
+  /**
+   * Shortcut name (e.g., 'CMD+K', 'CMD+B')
+   */
+  name: string;
+
+  /**
+   * Element to attach the shortcut to
+   */
+  on: HTMLElement | Document;
+
+  /**
+   * Callback function to execute when shortcut is triggered
+   */
+  callback: (event: KeyboardEvent) => void;
+}
+
+/**
+ * Shortcut class for handling keyboard shortcuts
+ *
+ * Listens for keydown events on the specified element and executes
+ * the callback when the configured key combination is pressed.
+ */
+export class Shortcut {
+  /**
+   * Shortcut name
+   */
+  public name: string;
+
+  /**
+   * Parsed modifier commands state
+   */
+  private commands: Record<ModifierKey, boolean>;
+
+  /**
+   * Parsed key codes to match
+   */
+  private keys: Record<string, boolean>;
+
+  /**
+   * Element the shortcut is attached to
+   */
+  private element: HTMLElement | Document;
+
+  /**
+   * Callback to execute when shortcut is triggered
+   */
+  private callback: (event: KeyboardEvent) => void;
+
+  /**
+   * Bound event handler for removal
+   */
+  private executeShortcut: EventListener;
+
+  /**
+   * Creates a new Shortcut instance
+   * @param options - Configuration options
+   */
+  constructor(options: ShortcutOptions) {
+    this.commands = {
+      SHIFT: false,
+      CMD: false,
+      ALT: false,
+    };
+    this.keys = {};
+    this.name = options.name;
+    this.element = options.on;
+    this.callback = options.callback;
+
+    this.parseShortcutName(options.name);
+
+    this.executeShortcut = (event: Event): void => {
+      this.execute(event as KeyboardEvent);
+    };
+
+    this.element.addEventListener('keydown', this.executeShortcut, false);
+  }
+
+  /**
+   * Removes the shortcut event listener
+   */
+  public remove(): void {
+    this.element.removeEventListener('keydown', this.executeShortcut);
+  }
+
+  /**
+   * Parses the shortcut name and extracts modifier keys and regular keys
+   * @param name - Shortcut name like 'CMD+K' or 'SHIFT+CMD+B'
+   */
+  private parseShortcutName(name: string): void {
+    const parts = name.split('+');
+
+    for (const part of parts) {
+      const upperPart = part.toUpperCase();
+      const modifierKey = findModifierKey(upperPart);
+
+      if (modifierKey !== undefined) {
+        this.commands[modifierKey] = true;
+      } else {
+        this.keys[upperPart] = true;
+      }
+    }
+  }
+
+  /**
+   * Checks if all modifier commands match the event
+   * @param event - Keyboard event to check
+   * @returns True if all modifiers match
+   */
+  private checkModifiers(event: KeyboardEvent): boolean {
+    const eventModifiers: Record<ModifierKey, boolean> = {
+      CMD: event.ctrlKey || event.metaKey,
+      SHIFT: event.shiftKey,
+      ALT: event.altKey,
+    };
+
+    const modifierKeys = Object.keys(this.commands) as ModifierKey[];
+
+    return modifierKeys.every(
+      (command) => this.commands[command] === eventModifiers[command]
+    );
+  }
+
+  /**
+   * Checks if all required keys match the event
+   * @param event - Keyboard event to check
+   * @returns True if all keys match
+   */
+  private checkKeys(event: KeyboardEvent): boolean {
+    const requiredKeys = Object.keys(this.keys);
+
+    return requiredKeys.every((key) => {
+      const expectedCode = KEY_CODES[key];
+
+      return event.code === expectedCode;
+    });
+  }
+
+  /**
+   * Executes the callback if the keyboard event matches the shortcut
+   * @param event - Keyboard event to check
+   */
+  private execute(event: KeyboardEvent): void {
+    const commandsMatch = this.checkModifiers(event);
+    const keysMatch = this.checkKeys(event);
+
+    if (commandsMatch && keysMatch) {
+      this.callback(event);
+    }
+  }
+}
+

package/src/components/utils/shortcuts.ts

@@ -0,0 +1,113 @@
+import { Shortcut } from './shortcut';
+
+/**
+ * Contains keyboard and mouse events binded on each Block by Block Manager
+ */
+
+/**
+ * ShortcutData interface
+ * Each shortcut must have name and handler
+ * `name` is a shortcut, like 'CMD+K', 'CMD+B' etc
+ * `handler` is a callback
+ * @interface ShortcutData
+ */
+export interface ShortcutData {
+
+  /**
+   * Shortcut name
+   * Ex. CMD+I, CMD+B ....
+   */
+  name: string;
+
+  /**
+   * Shortcut handler
+   */
+  handler(event: KeyboardEvent): void;
+
+  /**
+   * Element handler should be added for
+   */
+  on: HTMLElement | Document;
+}
+
+/**
+ * @class Shortcut
+ * @classdesc Allows to register new shortcut
+ *
+ * Internal Shortcuts Module
+ */
+class ShortcutsClass {
+  /**
+   * All registered shortcuts
+   * @type {Map<HTMLElement | Document, Shortcut[]>}
+   */
+  private registeredShortcuts: Map<HTMLElement | Document, Shortcut[]> = new Map();
+
+  /**
+   * Register shortcut
+   * @param shortcut - shortcut options
+   */
+  public add(shortcut: ShortcutData): void {
+    const foundShortcut = this.findShortcut(shortcut.on, shortcut.name);
+
+    if (foundShortcut) {
+      throw Error(
+        `Shortcut ${shortcut.name} is already registered for ${shortcut.on}. Please remove it before add a new handler.`
+      );
+    }
+
+    const newShortcut = new Shortcut({
+      name: shortcut.name,
+      on: shortcut.on,
+      callback: shortcut.handler,
+    });
+    const shortcuts = this.registeredShortcuts.get(shortcut.on) || [];
+
+    this.registeredShortcuts.set(shortcut.on, [...shortcuts, newShortcut]);
+  }
+
+  /**
+   * Remove shortcut
+   * @param element - Element shortcut is set for
+   * @param name - shortcut name
+   */
+  public remove(element: HTMLElement | Document, name: string): void {
+    const shortcut = this.findShortcut(element, name);
+
+    if (!shortcut) {
+      return;
+    }
+
+    shortcut.remove();
+
+    const shortcuts = this.registeredShortcuts.get(element);
+
+    if (!shortcuts) {
+      return;
+    }
+
+    const filteredShortcuts = shortcuts.filter(el => el !== shortcut);
+
+    if (filteredShortcuts.length === 0) {
+      this.registeredShortcuts.delete(element);
+
+      return;
+    }
+
+    this.registeredShortcuts.set(element, filteredShortcuts);
+  }
+
+  /**
+   * Get Shortcut instance if exist
+   * @param element - Element shorcut is set for
+   * @param shortcut - shortcut name
+   * @returns {number} index - shortcut index if exist
+   */
+  private findShortcut(element: HTMLElement | Document, shortcut: string): Shortcut | void {
+    const shortcuts = this.registeredShortcuts.get(element) || [];
+
+    return shortcuts.find(({ name }) => name === shortcut);
+  }
+}
+
+export const Shortcuts = new ShortcutsClass();

package/src/components/utils/tools.ts

@@ -0,0 +1,105 @@
+import type { BlockToolAdapter } from '../tools/block';
+import type { ToolboxConfigEntry } from '@/types';
+import { isFunction, isString } from '../utils';
+
+/**
+ * Interface for i18n instance needed by tool utilities
+ */
+export interface I18nInstance {
+  t(key: string, vars?: Record<string, string | number>): string;
+  has(key: string): boolean;
+}
+
+/**
+ * Check if tool has valid conversion config for export or import.
+ * @param tool - tool to check
+ * @param direction - export for tool to merge from, import for tool to merge to
+ */
+export const isToolConvertable = (tool: BlockToolAdapter, direction: 'export' | 'import'): boolean => {
+  if (!tool.conversionConfig) {
+    return false;
+  }
+
+  const conversionProp = tool.conversionConfig[direction];
+
+  return isFunction(conversionProp) || isString(conversionProp);
+};
+
+/**
+ * Try to translate a key in the toolNames namespace.
+ *
+ * @param i18n - I18n instance
+ * @param key - The key to look up (without the toolNames prefix)
+ * @returns The translated string or undefined if not found
+ */
+const tryTranslate = (i18n: I18nInstance, key: string): string | undefined => {
+  const fullKey = `toolNames.${key}`;
+
+  return i18n.has(fullKey) ? i18n.t(fullKey) : undefined;
+};
+
+/**
+ * Translate a toolbox entry title using the i18n system.
+ *
+ * Priority:
+ * 1. If titleKey is set, look up toolNames.{titleKey}
+ * 2. If title is set, look up toolNames.{title} (for external tools without titleKey)
+ * 3. If fallback is set, look up toolNames.{fallback} (for tools without title)
+ * 4. Return the first available string: title or fallback
+ *
+ * @param i18n - I18n instance
+ * @param entry - Toolbox config entry with title and optional titleKey
+ * @param fallback - Fallback string if no translation or title exists
+ * @returns Translated title string
+ */
+export const translateToolTitle = (i18n: I18nInstance, entry: ToolboxConfigEntry, fallback = ''): string => {
+  // Try titleKey first (explicit translation key)
+  const titleKeyTranslation = entry.titleKey ? tryTranslate(i18n, entry.titleKey) : undefined;
+
+  if (titleKeyTranslation !== undefined) {
+    return titleKeyTranslation;
+  }
+
+  // Try title as translation key (for external tools without titleKey)
+  const titleTranslation = entry.title ? tryTranslate(i18n, entry.title) : undefined;
+
+  if (titleTranslation !== undefined) {
+    return titleTranslation;
+  }
+
+  if (entry.title) {
+    return entry.title;
+  }
+
+  // Try fallback as translation key (for tools without title)
+  const fallbackTranslation = fallback ? tryTranslate(i18n, fallback) : undefined;
+
+  return fallbackTranslation ?? fallback;
+};
+
+/**
+ * Translate a tool name using the toolNames namespace.
+ *
+ * Priority:
+ * 1. If titleKey is set, look up toolNames.{titleKey}
+ * 2. If title is set, look up toolNames.{title} (for external tools without titleKey)
+ * 3. Return the title as-is
+ *
+ * @param i18n - I18n instance
+ * @param titleKey - Translation key (e.g., 'bold', 'link', 'text')
+ * @param title - Fallback title string (e.g., 'Bold', 'Link', 'Text')
+ * @returns Translated tool name, or the title as fallback
+ */
+export const translateToolName = (i18n: I18nInstance, titleKey: string | undefined, title: string): string => {
+  // Try explicit titleKey first
+  const titleKeyTranslation = titleKey ? tryTranslate(i18n, titleKey) : undefined;
+
+  if (titleKeyTranslation !== undefined) {
+    return titleKeyTranslation;
+  }
+
+  // Try title as translation key (for external tools without titleKey)
+  const titleTranslation = tryTranslate(i18n, title);
+
+  return titleTranslation ?? title;
+};