@jackuait/blok 0.4.1 → 0.4.2

package/src/components/flipper.ts

@@ -0,0 +1,481 @@
+import { DomIterator } from './domIterator';
+import { isFunction, keyCodes } from './utils';
+
+/**
+ * Flipper construction options
+ * @interface FlipperOptions
+ * @internal
+ */
+export interface FlipperOptions {
+  /**
+   * CSS-modifier for focused item
+   */
+  focusedItemClass?: string;
+
+  /**
+   * Allow handling keyboard events dispatched from contenteditable elements
+   */
+  handleContentEditableTargets?: boolean;
+
+  /**
+   * If flipping items are the same for all Block (for ex. Toolbox), ypu can pass it on constructing
+   */
+  items?: HTMLElement[];
+
+  /**
+   * Optional callback for button click
+   */
+  activateCallback?: (item: HTMLElement) => void;
+
+  /**
+   * List of keys allowed for handling.
+   * Can include codes of the following keys:
+   *  - Tab
+   *  - Enter
+   *  - Arrow up
+   *  - Arrow down
+   *  - Arrow right
+   *  - Arrow left
+   * If not specified all keys are enabled
+   */
+  allowedKeys?: number[];
+
+  /**
+   * Callback fired when ArrowLeft is pressed.
+   * Used by nested popovers to close and return focus to parent.
+   */
+  onArrowLeft?: () => void;
+}
+
+/**
+ * Flipper is a component that iterates passed items array by TAB or Arrows and clicks it by ENTER
+ * @internal
+ */
+export class Flipper {
+  /**
+   * True if flipper is currently activated
+   */
+  public get isActivated(): boolean {
+    return this.activated;
+  }
+
+  /**
+   * Instance of flipper iterator
+   */
+  private readonly iterator: DomIterator | null = null;
+
+  /**
+   * Flag that defines activation status
+   */
+  private activated = false;
+
+  /**
+   * Skip moving focus on the next Tab press when initial focus was pre-set
+   */
+  private skipNextTabFocus = false;
+
+  /**
+   * True if flipper should handle events coming from contenteditable elements
+   */
+  private handleContentEditableTargets: boolean;
+
+  /**
+   * List codes of the keys allowed for handling
+   */
+  private readonly allowedKeys: number[];
+
+  /**
+   * Call back for button click/enter
+   */
+  private readonly activateCallback?: (item: HTMLElement) => void;
+
+  /**
+   * Contains list of callbacks to be executed on each flip
+   */
+  private flipCallbacks: Array<() => void> = [];
+
+  /**
+   * Callback fired when ArrowLeft is pressed.
+   * Used by nested popovers to close and return focus to parent.
+   */
+  private readonly onArrowLeftCallback?: () => void;
+
+  /**
+   * @param options - different constructing settings
+   */
+  constructor(options: FlipperOptions) {
+    this.iterator = new DomIterator(options.items || [], options.focusedItemClass ?? '');
+    this.activateCallback = options.activateCallback;
+    this.allowedKeys = options.allowedKeys || Flipper.usedKeys;
+    this.handleContentEditableTargets = options.handleContentEditableTargets ?? false;
+    this.onArrowLeftCallback = options.onArrowLeft;
+  }
+
+  /**
+   * Array of keys (codes) that is handled by Flipper
+   * Used to:
+   *  - preventDefault only for this keys, not all keydowns (@see constructor)
+   *  - to skip external behaviours only for these keys, when filler is activated (@see BlockEvents@arrowRightAndDown)
+   */
+  public static get usedKeys(): number[] {
+    return [
+      keyCodes.TAB,
+      keyCodes.LEFT,
+      keyCodes.RIGHT,
+      keyCodes.ENTER,
+      keyCodes.UP,
+      keyCodes.DOWN,
+    ];
+  }
+
+  /**
+   * Active tab/arrows handling by flipper
+   * @param items - Some modules (like, InlineToolbar, BlockSettings) might refresh buttons dynamically
+   * @param cursorPosition - index of the item that should be focused once flipper is activated
+   */
+  public activate(items?: HTMLElement[], cursorPosition?: number): void {
+    this.activated = true;
+    if (items) {
+      this.iterator?.setItems(items);
+    }
+
+    if (cursorPosition !== undefined) {
+      this.iterator?.setCursor(cursorPosition);
+    }
+
+    /**
+     * Listening all keydowns on document and react on TAB/Enter press
+     * TAB will leaf iterator items
+     * ENTER will click the focused item
+     *
+     * Note: the event should be handled in capturing mode on following reasons:
+     * - prevents plugins inner keydown handlers from being called while keyboard navigation
+     * - otherwise this handler will be called at the moment it is attached which causes false flipper firing (see https://techread.me/js-addeventlistener-fires-for-past-events/)
+     */
+    document.addEventListener('keydown', this.onKeyDown, true);
+    window.addEventListener('keydown', this.onKeyDown, true);
+  }
+
+  /**
+   * Disable tab/arrows handling by flipper
+   */
+  public deactivate(): void {
+    this.activated = false;
+    this.dropCursor();
+    this.skipNextTabFocus = false;
+
+    document.removeEventListener('keydown', this.onKeyDown, true);
+    window.removeEventListener('keydown', this.onKeyDown, true);
+  }
+
+  /**
+   * Focus first item
+   */
+  public focusFirst(): void {
+    this.dropCursor();
+    this.flipRight();
+  }
+
+  /**
+   * Focus item at specified position without triggering flip callbacks
+   * @param position - index of item to focus. Negative value clears focus.
+   * @param options - optional settings for focus behavior
+   * @param options.skipNextTab - if true, skip the next Tab press (default: true for position 0 when no current item)
+   */
+  public focusItem(position: number, options?: { skipNextTab?: boolean }): void {
+    const iterator = this.iterator;
+
+    if (!iterator) {
+      return;
+    }
+
+    if (!iterator.hasItems()) {
+      return;
+    }
+
+    if (position < 0) {
+      iterator.dropCursor();
+
+      return;
+    }
+
+    const shouldSkipNextTab = options?.skipNextTab ?? (!iterator.currentItem && position === 0);
+
+    if (shouldSkipNextTab) {
+      this.skipNextTabFocus = true;
+    }
+
+    iterator.setCursor(position);
+  }
+
+  /**
+   * Focuses previous flipper iterator item
+   */
+  public flipLeft(): void {
+    this.iterator?.previous();
+    this.flipCallback();
+  }
+
+  /**
+   * Focuses next flipper iterator item
+   */
+  public flipRight(): void {
+    this.iterator?.next();
+    this.flipCallback();
+  }
+
+  /**
+   * Return true if some button is focused
+   */
+  public hasFocus(): boolean {
+    return !!this.iterator?.currentItem;
+  }
+
+  /**
+   * Checks if current focused item has children (nested menu)
+   * Looks for data-blok-has-children attribute on the current item
+   */
+  private currentItemHasChildren(): boolean {
+    const currentItem = this.iterator?.currentItem;
+
+    if (!currentItem) {
+      return false;
+    }
+
+    return currentItem.hasAttribute('data-blok-has-children');
+  }
+
+  /**
+   * Registers a function that should be executed on each navigation action
+   * @param cb - function to execute
+   */
+  public onFlip(cb: () => void): void {
+    this.flipCallbacks.push(cb);
+  }
+
+  /**
+   * Unregisters a function that is executed on each navigation action
+   * @param cb - function to stop executing
+   */
+  public removeOnFlip(cb: () => void): void {
+    this.flipCallbacks = this.flipCallbacks.filter(fn => fn !== cb);
+  }
+
+  /**
+   * Drops flipper's iterator cursor
+   * @see DomIterator#dropCursor
+   */
+  private dropCursor(): void {
+    this.iterator?.dropCursor();
+  }
+
+  /**
+   * Get numeric keyCode from KeyboardEvent.key for backward compatibility
+   * @param event - keyboard event
+   * @returns numeric keyCode or null if not recognized
+   */
+  private getKeyCode(event: KeyboardEvent): number | null {
+    const keyToCodeMap: Record<string, number> = {
+      'Tab': keyCodes.TAB,
+      'Enter': keyCodes.ENTER,
+      'ArrowLeft': keyCodes.LEFT,
+      'ArrowRight': keyCodes.RIGHT,
+      'ArrowUp': keyCodes.UP,
+      'ArrowDown': keyCodes.DOWN,
+    };
+
+    return keyToCodeMap[event.key] ?? null;
+  }
+
+  /**
+   * KeyDown event handler
+   * @param event - keydown event
+   */
+  private onKeyDown = (event: KeyboardEvent): void => {
+    const target = event.target as HTMLElement | null;
+
+    if (this.shouldSkipTarget(target, event)) {
+      return;
+    }
+
+    const keyCode = this.getKeyCode(event);
+    const isDirectionalArrow = keyCode === keyCodes.LEFT
+      || keyCode === keyCodes.RIGHT
+      || keyCode === keyCodes.UP
+      || keyCode === keyCodes.DOWN;
+
+    /**
+     * Allow selecting text with Shift combined with arrow keys by delegating handling to the browser.
+     * Other Shift-based combinations (for example Shift+Tab) are still handled by Flipper.
+     */
+    if (event.shiftKey && isDirectionalArrow) {
+      return;
+    }
+
+    const isReady = this.isEventReadyForHandling(event);
+
+    if (!isReady) {
+      return;
+    }
+
+    /**
+     * For Enter key, only handle it if there's a focused item.
+     * Otherwise, let the event propagate to allow block splitting etc.
+     */
+    if (keyCode === keyCodes.ENTER && !this.iterator?.currentItem) {
+      return;
+    }
+
+    /**
+     * Stop propagation to prevent plugin-level handlers from being called
+     * while Flipper manages keyboard navigation.
+     */
+    event.stopPropagation();
+    event.stopImmediatePropagation();
+
+
+    /**
+     * Prevent only used keys default behaviour
+     * (allows to navigate by ARROW DOWN, for example)
+     */
+    if (keyCode !== null && Flipper.usedKeys.includes(keyCode)) {
+      event.preventDefault();
+    }
+
+    switch (keyCode) {
+      case keyCodes.TAB:
+        this.handleTabPress(event);
+        break;
+      case keyCodes.LEFT:
+        // ArrowLeft triggers callback only if callback is set (for nested popovers)
+        if (this.onArrowLeftCallback) {
+          this.onArrowLeftCallback();
+        }
+        break;
+      case keyCodes.UP:
+        this.flipLeft();
+        break;
+      case keyCodes.RIGHT:
+        // ArrowRight clicks the focused item to open nested popover, but only if item has children
+        // Otherwise, do nothing (don't activate items without nested menu)
+        if (this.iterator?.currentItem && this.currentItemHasChildren()) {
+          this.handleEnterPress(event);
+        }
+        break;
+      case keyCodes.DOWN:
+        this.flipRight();
+        break;
+      case keyCodes.ENTER:
+        this.handleEnterPress(event);
+        break;
+    }
+  };
+
+  /**
+   * This function is fired before handling flipper keycodes
+   * The result of this function defines if it is need to be handled or not
+   * @param {KeyboardEvent} event - keydown keyboard event
+   * @returns {boolean}
+   */
+  private isEventReadyForHandling(event: KeyboardEvent): boolean {
+    const keyCode = this.getKeyCode(event);
+
+    return this.activated && keyCode !== null && this.allowedKeys.includes(keyCode);
+  }
+
+  /**
+   * Enables or disables handling events dispatched from contenteditable elements
+   * @param value - true if events from contenteditable elements should be handled
+   */
+  public setHandleContentEditableTargets(value: boolean): void {
+    this.handleContentEditableTargets = value;
+  }
+
+  /**
+   * When flipper is activated tab press will leaf the items
+   * @param {KeyboardEvent} event - tab keydown event
+   */
+  private handleTabPress(event: KeyboardEvent): void {
+    /** this property defines leaf direction */
+    const shiftKey = event.shiftKey;
+    const direction = shiftKey ? DomIterator.directions.LEFT : DomIterator.directions.RIGHT;
+
+    if (this.skipNextTabFocus) {
+      this.skipNextTabFocus = false;
+
+      return;
+    }
+
+    switch (direction) {
+      case DomIterator.directions.RIGHT:
+        this.flipRight();
+        break;
+      case DomIterator.directions.LEFT:
+        this.flipLeft();
+        break;
+    }
+  }
+
+  /**
+   * Delegates external keyboard events to the flipper handler.
+   * @param event - keydown event captured outside the flipper
+   */
+  public handleExternalKeydown(event: KeyboardEvent): void {
+    this.onKeyDown(event);
+  }
+
+  /**
+   * Enter press will click current item if flipper is activated
+   * @param {KeyboardEvent} event - enter keydown event
+   */
+  private handleEnterPress(event: KeyboardEvent): void {
+    if (!this.activated) {
+      return;
+    }
+
+    if (this.iterator?.currentItem) {
+      /**
+       * Stop Enter propagation only if flipper is ready to select focused item
+       */
+      event.stopPropagation();
+      event.preventDefault();
+      this.iterator.currentItem.click();
+    }
+
+    if (isFunction(this.activateCallback) && this.iterator?.currentItem) {
+      this.activateCallback(this.iterator.currentItem);
+    }
+  }
+
+  /**
+   * Fired after flipping in any direction
+   */
+  private flipCallback(): void {
+    if (this.iterator?.currentItem) {
+      this.iterator.currentItem.scrollIntoViewIfNeeded?.();
+    }
+
+    this.flipCallbacks.forEach(cb => cb());
+  }
+
+  /**
+   * Determine if keyboard events coming from a target should be skipped
+   * @param target - event target element
+   * @param event - keyboard event being handled
+   */
+  private shouldSkipTarget(target: HTMLElement | null, event: KeyboardEvent): boolean {
+    if (!target) {
+      return false;
+    }
+
+    const isNativeInput = target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement;
+    const isNavigationKey = event.key === 'Tab' || event.key === 'ArrowUp' || event.key === 'ArrowDown' || event.key === 'Enter' || event.key === 'ArrowRight' || event.key === 'ArrowLeft';
+    const shouldHandleNativeInput = target.getAttribute('data-blok-flipper-navigation-target') === 'true' && isNavigationKey;
+    const isContentEditable = target.isContentEditable;
+    const isInlineToolInput = target.closest('[data-blok-link-tool-input-opened="true"]') !== null;
+
+    const shouldSkipContentEditable = isContentEditable && !this.handleContentEditableTargets;
+
+    return (isNativeInput && !shouldHandleNativeInput) || shouldSkipContentEditable || isInlineToolInput;
+  }
+}

package/src/components/i18n/i18next-loader.ts

@@ -0,0 +1,84 @@
+import type { i18n as I18nextInstance, InitOptions } from 'i18next';
+import type { I18nDictionary } from '../../../types/configs/i18n-dictionary';
+import type { SupportedLocale } from '../../../types/configs/i18n-config';
+import { englishDictionary } from './lightweight-i18n';
+
+/**
+ * i18next instance type after initialization
+ */
+export type InitializedI18next = I18nextInstance;
+
+/**
+ * Result of initializing i18next
+ */
+export interface I18nextInitResult {
+  instance: InitializedI18next;
+  t: (key: string, vars?: Record<string, string | number>) => string;
+  has: (key: string) => boolean;
+  setDictionary: (dictionary: I18nDictionary) => void;
+  changeLanguage: (locale: SupportedLocale) => Promise<void>;
+}
+
+/**
+ * Dynamically load and initialize i18next.
+ * This is only called when a non-English locale is needed.
+ *
+ * @param initialLocale - The locale to initialize with
+ * @param localeConfig - The loaded locale configuration
+ * @returns Initialized i18next wrapper
+ */
+export const loadI18next = async (
+  initialLocale: SupportedLocale,
+  localeConfig: { dictionary: I18nDictionary }
+): Promise<I18nextInitResult> => {
+  // Dynamic import of i18next - this is the key to tree-shaking it out
+  const i18next = await import('i18next');
+
+  // Create a new instance (not the global one) for isolation
+  const instance = i18next.default.createInstance();
+
+  const initOptions: InitOptions = {
+    lng: initialLocale,
+    fallbackLng: 'en',
+    resources: {
+      en: {
+        translation: englishDictionary,
+      },
+      [initialLocale]: {
+        translation: localeConfig.dictionary,
+      },
+    },
+    interpolation: {
+      // Use single braces {var} to match existing format
+      prefix: '{',
+      suffix: '}',
+      escapeValue: false, // React/DOM handles escaping
+    },
+    // Return key if translation is missing (consistent behavior)
+    returnNull: false,
+    returnEmptyString: false,
+    // Don't parse keys as nested objects - we use flat keys with dots
+    keySeparator: false,
+    nsSeparator: false,
+  };
+
+  await instance.init(initOptions);
+
+  return {
+    instance,
+    t: (key: string, vars?: Record<string, string | number>): string => {
+      return instance.t(key, vars);
+    },
+    has: (key: string): boolean => {
+      return instance.exists(key);
+    },
+    setDictionary: (dictionary: I18nDictionary): void => {
+      const currentLang = instance.language;
+
+      instance.addResourceBundle(currentLang, 'translation', dictionary, true, true);
+    },
+    changeLanguage: async (locale: SupportedLocale): Promise<void> => {
+      await instance.changeLanguage(locale);
+    },
+  };
+}

package/src/components/i18n/lightweight-i18n.ts

@@ -0,0 +1,86 @@
+import type { I18nDictionary } from '../../../types/configs/i18n-dictionary';
+import enMessages from './locales/en/messages.json';
+
+/**
+ * Lightweight i18n implementation for English-only usage.
+ * Provides simple string interpolation without the overhead of i18next.
+ *
+ * For non-English locales, the full i18next-based implementation is loaded dynamically.
+ *
+ * @internal
+ */
+export class LightweightI18n {
+  /**
+   * Current dictionary (defaults to English)
+   */
+  private dictionary: I18nDictionary;
+
+  /**
+   * Custom overrides set via setDictionary
+   */
+  private overrides: I18nDictionary | null = null;
+
+  constructor() {
+    this.dictionary = enMessages;
+  }
+
+  /**
+   * Translate a key with optional interpolation.
+   *
+   * @param key - Translation key
+   * @param vars - Optional variables for interpolation
+   * @returns Translated string, or the key if not found
+   */
+  public t(key: string, vars?: Record<string, string | number>): string {
+    // Check overrides first, then fall back to base dictionary
+    const value = this.overrides?.[key] ?? this.dictionary[key];
+
+    if (value === undefined) {
+      return key;
+    }
+
+    if (vars === undefined) {
+      return value;
+    }
+
+    // Simple interpolation: replace {varName} with value
+    return value.replace(/\{(\w+)\}/g, (match, varName: string) => {
+      const replacement = vars[varName];
+
+      return replacement !== undefined ? String(replacement) : match;
+    });
+  }
+
+  /**
+   * Check if a translation exists
+   */
+  public has(key: string): boolean {
+    return (this.overrides?.[key] ?? this.dictionary[key]) !== undefined;
+  }
+
+  /**
+   * Add custom dictionary overrides
+   */
+  public setDictionary(dictionary: I18nDictionary): void {
+    this.overrides = { ...this.overrides, ...dictionary };
+  }
+
+  /**
+   * Get the current locale
+   */
+  public getLocale(): 'en' {
+    return 'en';
+  }
+
+  /**
+   * Get text direction (always LTR for English)
+   */
+  public getDirection(): 'ltr' {
+    return 'ltr';
+  }
+}
+
+/**
+ * English dictionary for synchronous access
+ */
+export const englishDictionary = enMessages;