@jackuait/blok 0.4.1 → 0.4.2

package/src/components/modules/api/inlineToolbar.ts

@@ -0,0 +1,33 @@
+import type { InlineToolbar } from '../../../../types/api/inline-toolbar';
+import { Module } from '../../__module';
+
+/**
+ * @class InlineToolbarAPI
+ * Provides methods for working with the Inline Toolbar
+ */
+export class InlineToolbarAPI extends Module {
+  /**
+   * Available methods
+   * @returns {InlineToolbar}
+   */
+  public get methods(): InlineToolbar {
+    return {
+      close: (): void => this.close(),
+      open: (): void => this.open(),
+    };
+  }
+
+  /**
+   * Open Inline Toolbar
+   */
+  public open(): void {
+    void this.Blok.InlineToolbar.tryToShow();
+  }
+
+  /**
+   * Close Inline Toolbar
+   */
+  public close(): void {
+    this.Blok.InlineToolbar.close();
+  }
+}

package/src/components/modules/api/listeners.ts

@@ -0,0 +1,56 @@
+import type { Listeners } from '../../../../types/api';
+import { Module } from '../../__module';
+
+/**
+ * @class ListenersAPI
+ * Provides with methods working with DOM Listener
+ */
+export class ListenersAPI extends Module {
+  /**
+   * Available methods
+   * @returns {Listeners}
+   */
+  public get methods(): Listeners {
+    return {
+      on: (element: HTMLElement, eventType, handler, useCapture): string | undefined =>
+        this.on(element, eventType, handler, useCapture),
+      off: (element, eventType, handler, useCapture): void => this.off(element, eventType, handler, useCapture),
+      offById: (id): void => this.offById(id),
+    };
+  }
+
+  /**
+   * Ads a DOM event listener. Return it's id.
+   * @param {HTMLElement} element - Element to set handler to
+   * @param {string} eventType - event type
+   * @param {() => void} handler - event handler
+   * @param {boolean} useCapture - capture event or not
+   */
+  public on(
+    element: HTMLElement,
+    eventType: string,
+    handler: () => void,
+    useCapture?: boolean
+  ): string | undefined {
+    return this.listeners.on(element, eventType, handler, useCapture);
+  }
+
+  /**
+   * Removes DOM listener from element
+   * @param {Element} element - Element to remove handler from
+   * @param eventType - event type
+   * @param handler - event handler
+   * @param {boolean} useCapture - capture event or not
+   */
+  public off(element: Element, eventType: string, handler: () => void, useCapture?: boolean): void {
+    this.listeners.off(element, eventType, handler, useCapture);
+  }
+
+  /**
+   * Removes DOM listener by the listener id
+   * @param id - id of the listener to remove
+   */
+  public offById(id: string): void {
+    this.listeners.offById(id);
+  }
+}

package/src/components/modules/api/notifier.ts

@@ -0,0 +1,46 @@
+import type { Notifier as INotifier } from '../../../../types/api';
+import { Notifier } from '../../utils/notifier';
+import type { ConfirmNotifierOptions, NotifierOptions, PromptNotifierOptions } from '../../utils/notifier/types';
+import { Module } from '../../__module';
+import type { ModuleConfig } from '../../../types-internal/module-config';
+
+/**
+ *
+ */
+export class NotifierAPI extends Module {
+  /**
+   * Notifier utility Instance
+   */
+  private notifier: Notifier;
+
+  /**
+   * @param moduleConfiguration - Module Configuration
+   * @param moduleConfiguration.config - Blok's config
+   * @param moduleConfiguration.eventsDispatcher - Blok's event dispatcher
+   */
+  constructor({ config, eventsDispatcher }: ModuleConfig) {
+    super({
+      config,
+      eventsDispatcher,
+    });
+
+    this.notifier = new Notifier();
+  }
+
+  /**
+   * Available methods
+   */
+  public get methods(): INotifier {
+    return {
+      show: (options: NotifierOptions | ConfirmNotifierOptions | PromptNotifierOptions): void => this.show(options),
+    };
+  }
+
+  /**
+   * Show notification
+   * @param {NotifierOptions} options - message option
+   */
+  public show(options: NotifierOptions | ConfirmNotifierOptions | PromptNotifierOptions): void {
+    return this.notifier.show(options);
+  }
+}

package/src/components/modules/api/readonly.ts

@@ -0,0 +1,39 @@
+import type { ReadOnly } from '../../../../types/api';
+import { Module } from '../../__module';
+
+/**
+ * @class ReadOnlyAPI
+ * @classdesc ReadOnly API
+ */
+export class ReadOnlyAPI extends Module {
+  /**
+   * Available methods
+   */
+  public get methods(): ReadOnly {
+    const getIsEnabled = (): boolean => this.isEnabled;
+
+     
+    return {
+      toggle: (state): Promise<boolean> => this.toggle(state),
+      get isEnabled(): boolean {
+        return getIsEnabled();
+      },
+    };
+  }
+
+  /**
+   * Set or toggle read-only state
+   * @param {boolean|undefined} state - set or toggle state
+   * @returns {boolean} current value
+   */
+  public toggle(state?: boolean): Promise<boolean> {
+    return this.Blok.ReadOnly.toggle(state);
+  }
+
+  /**
+   * Returns current read-only state
+   */
+  public get isEnabled(): boolean {
+    return this.Blok.ReadOnly.isEnabled;
+  }
+}

package/src/components/modules/api/sanitizer.ts

@@ -0,0 +1,30 @@
+import type { Sanitizer as ISanitizer } from '../../../../types/api';
+import type { SanitizerConfig } from '../../../../types/configs';
+import { Module } from '../../__module';
+import { clean } from '../../utils/sanitizer';
+
+/**
+ * @class SanitizerAPI
+ * Provides Blok Sanitizer that allows developers to clean their HTML
+ */
+export class SanitizerAPI extends Module {
+  /**
+   * Available methods
+   * @returns {SanitizerConfig}
+   */
+  public get methods(): ISanitizer {
+    return {
+      clean: (taintString, config): string => this.clean(taintString, config),
+    };
+  }
+
+  /**
+   * Perform sanitizing of a string
+   * @param {string} taintString - what to sanitize
+   * @param {SanitizerConfig} config - sanitizer config
+   * @returns {string}
+   */
+  public clean(taintString: string, config: SanitizerConfig): string {
+    return clean(taintString, config);
+  }
+}

package/src/components/modules/api/saver.ts

@@ -0,0 +1,52 @@
+import type { Saver } from '../../../../types/api';
+import type { OutputData } from '../../../../types';
+import { logLabeled } from '../../utils';
+import { Module } from '../../__module';
+
+/**
+ * @class SaverAPI
+ * provides with methods to save data
+ */
+export class SaverAPI extends Module {
+  /**
+   * Available methods
+   * @returns {Saver}
+   */
+  public get methods(): Saver {
+    return {
+      save: (): Promise<OutputData> => this.save(),
+    };
+  }
+
+  /**
+   * Return Blok's data
+   * @returns {OutputData}
+   */
+  public async save(): Promise<OutputData> {
+    const errorText = 'Blok\'s content can not be saved in read-only mode';
+
+    if (this.Blok.ReadOnly.isEnabled) {
+      logLabeled(errorText, 'warn');
+
+      throw new Error(errorText);
+    }
+
+    const savedData = await this.Blok.Saver.save();
+
+    if (savedData !== undefined) {
+      return savedData;
+    }
+
+    const lastError = this.Blok.Saver.getLastSaveError?.();
+
+    if (lastError instanceof Error) {
+      throw lastError;
+    }
+
+    const errorMessage = lastError !== undefined
+      ? String(lastError)
+      : 'Blok\'s content can not be saved because collecting data failed';
+
+    throw new Error(errorMessage);
+  }
+}

package/src/components/modules/api/selection.ts

@@ -0,0 +1,48 @@
+import { SelectionUtils } from '../../selection';
+import type { Selection as SelectionAPIInterface } from '../../../../types/api';
+import { Module } from '../../__module';
+
+/**
+ * @class SelectionAPI
+ * Provides with methods working with SelectionUtils
+ */
+export class SelectionAPI extends Module {
+  /**
+   * Global SelectionUtils instance
+   */
+  private selectionUtils = new SelectionUtils();
+
+  /**
+   * Available methods
+   * @returns {SelectionAPIInterface}
+   */
+  public get methods(): SelectionAPIInterface {
+    return {
+      findParentTag: (tagName: string, className?: string): HTMLElement | null => this.findParentTag(tagName, className),
+      expandToTag: (node: HTMLElement): void => this.expandToTag(node),
+      save: () => this.selectionUtils.save(),
+      restore: () => this.selectionUtils.restore(),
+      setFakeBackground: () => this.selectionUtils.setFakeBackground(),
+      removeFakeBackground: () => this.selectionUtils.removeFakeBackground(),
+      clearFakeBackground: () => this.selectionUtils.clearFakeBackground(),
+    };
+  }
+
+  /**
+   * Looks ahead from selection and find passed tag with class name
+   * @param {string} tagName - tag to find
+   * @param {string} className - tag's class name
+   * @returns {HTMLElement|null}
+   */
+  public findParentTag(tagName: string, className?: string): HTMLElement | null {
+    return this.selectionUtils.findParentTag(tagName, className);
+  }
+
+  /**
+   * Expand selection to passed tag
+   * @param {HTMLElement} node - tag that should contain selection
+   */
+  public expandToTag(node: HTMLElement): void {
+    this.selectionUtils.expandToTag(node);
+  }
+}

package/src/components/modules/api/styles.ts

@@ -0,0 +1,72 @@
+import type { Styles } from '../../../../types/api';
+import { Module } from '../../__module';
+
+/**
+ * StylesAPI provides CSS class names for tool authors.
+ *
+ * These are single class names that can be safely used with classList.add():
+ * @example
+ * element.classList.add(api.styles.block);
+ *
+ * They can also be extended using tailwind-merge:
+ * @example
+ * import { twMerge } from '@jackuait/blok/utils/tw';
+ * const customBlock = twMerge(api.styles.block, 'my-4 bg-gray-100');
+ */
+export class StylesAPI extends Module {
+  /**
+   * Exported CSS class names for tool styling.
+   * These are single class names that can be safely used with classList.add().
+   * The actual styles are defined in src/styles/main.css using @apply.
+   */
+  public get classes(): Styles {
+    return {
+      /**
+       * Base Block styles - applied to block tool wrappers
+       * Includes placeholder styling via pseudo-element
+       */
+      block: 'blok-block',
+
+      /**
+       * Inline Tools styles
+       */
+      inlineToolButton: 'blok-inline-tool-button',
+      inlineToolButtonActive: 'blok-inline-tool-button--active',
+
+      /**
+       * Input element styles with Firefox placeholder workaround
+       */
+      input: 'blok-input',
+
+      /**
+       * Loader styles with spinning animation
+       */
+      loader: 'blok-loader',
+
+      /**
+       * Button styles with hover state
+       */
+      button: 'blok-button',
+
+      /**
+       * Settings button base styles with mobile responsive sizing
+       */
+      settingsButton: 'blok-settings-button',
+
+      /**
+       * Settings button active state
+       */
+      settingsButtonActive: 'blok-settings-button--active',
+
+      /**
+       * Settings button focused state
+       */
+      settingsButtonFocused: 'blok-settings-button--focused',
+
+      /**
+       * Settings button focused with animation
+       */
+      settingsButtonFocusedAnimated: 'blok-settings-button--focused-animated',
+    };
+  }
+}

package/src/components/modules/api/toolbar.ts

@@ -0,0 +1,79 @@
+import type { Toolbar } from '../../../../types/api';
+import { Module } from '../../__module';
+import { logLabeled } from './../../utils';
+/**
+ * @class ToolbarAPI
+ * Provides methods for working with the Toolbar
+ */
+export class ToolbarAPI extends Module {
+  /**
+   * Available methods
+   * @returns {Toolbar}
+   */
+  public get methods(): Toolbar {
+    return {
+      close: (): void => this.close(),
+      open: (): void => this.open(),
+      toggleBlockSettings: (openingState?: boolean): void => this.toggleBlockSettings(openingState),
+      toggleToolbox: (openingState?: boolean): void => this.toggleToolbox(openingState),
+    };
+  }
+
+  /**
+   * Open toolbar
+   */
+  public open(): void {
+    this.Blok.Toolbar.moveAndOpen();
+  }
+
+  /**
+   * Close toolbar and all included elements
+   */
+  public close(): void {
+    this.Blok.Toolbar.close();
+  }
+
+  /**
+   * Toggles Block Setting of the current block
+   * @param {boolean} openingState —  opening state of Block Setting
+   */
+  public toggleBlockSettings(openingState?: boolean): void {
+    if (this.Blok.BlockManager.currentBlockIndex === -1) {
+      logLabeled('Could\'t toggle the Toolbar because there is no block selected ', 'warn');
+
+      return;
+    }
+
+    /** Check that opening state is set or not */
+    const canOpenBlockSettings = openingState ?? !this.Blok.BlockSettings.opened;
+
+    if (canOpenBlockSettings) {
+      this.Blok.Toolbar.moveAndOpen();
+      void this.Blok.BlockSettings.open();
+    } else {
+      this.Blok.BlockSettings.close();
+    }
+  }
+
+
+  /**
+   * Open toolbox
+   * @param {boolean} openingState - Opening state of toolbox
+   */
+  public toggleToolbox(openingState?: boolean): void {
+    if (this.Blok.BlockManager.currentBlockIndex === -1) {
+      logLabeled('Could\'t toggle the Toolbox because there is no block selected ', 'warn');
+
+      return;
+    }
+
+    const canOpenToolbox = openingState ?? !this.Blok.Toolbar.toolbox.opened;
+
+    if (canOpenToolbox) {
+      this.Blok.Toolbar.moveAndOpen();
+      this.Blok.Toolbar.toolbox.open();
+    } else {
+      this.Blok.Toolbar.toolbox.close();
+    }
+  }
+}

package/src/components/modules/api/tools.ts

@@ -0,0 +1,16 @@
+import type { Tools as ToolsAPIInterface } from '../../../../types/api';
+import { Module } from '../../__module';
+
+/**
+ * Provides methods for accessing installed Blok tools
+ */
+export class ToolsAPI extends Module {
+  /**
+   * Available methods
+   */
+  public get methods(): ToolsAPIInterface {
+    return {
+      getBlockTools: () => Array.from(this.Blok.Tools.blockTools.values()),
+    };
+  }
+}

package/src/components/modules/api/tooltip.ts

@@ -0,0 +1,67 @@
+import type { Tooltip as ITooltip } from '../../../../types/api';
+import type { TooltipOptions, TooltipContent } from '../../utils/tooltip';
+import { Module } from '../../__module';
+import type { ModuleConfig } from '../../../types-internal/module-config';
+import { hide, onHover, show } from '../../utils/tooltip';
+/**
+ * @class TooltipAPI
+ * @classdesc Tooltip API
+ */
+export class TooltipAPI extends Module {
+  /**
+   * @class
+   * @param moduleConfiguration - Module Configuration
+   * @param moduleConfiguration.config - Blok's config
+   * @param moduleConfiguration.eventsDispatcher - Blok's event dispatcher
+   */
+  constructor({ config, eventsDispatcher }: ModuleConfig) {
+    super({
+      config,
+      eventsDispatcher,
+    });
+  }
+
+  /**
+   * Available methods
+   */
+  public get methods(): ITooltip {
+    return {
+      show: (element: HTMLElement,
+        content: TooltipContent,
+        options?: TooltipOptions
+      ): void => this.show(element, content, options),
+      hide: (): void => this.hide(),
+      onHover: (element: HTMLElement,
+        content: TooltipContent,
+        options?: TooltipOptions
+      ): void => this.onHover(element, content, options),
+    };
+  }
+
+  /**
+   * Method show tooltip on element with passed HTML content
+   * @param {HTMLElement} element - element on which tooltip should be shown
+   * @param {TooltipContent} content - tooltip content
+   * @param {TooltipOptions} options - tooltip options
+   */
+  public show(element: HTMLElement, content: TooltipContent, options?: TooltipOptions): void {
+    show(element, content, options);
+  }
+
+  /**
+   * Method hides tooltip on HTML page
+   */
+  public hide(): void {
+    hide();
+  }
+
+  /**
+   * Decorator for showing Tooltip by mouseenter/mouseleave
+   * @param {HTMLElement} element - element on which tooltip should be shown
+   * @param {TooltipContent} content - tooltip content
+   * @param {TooltipOptions} options - tooltip options
+   */
+  public onHover(element: HTMLElement, content: TooltipContent, options?: TooltipOptions): void {
+    onHover(element, content, options);
+  }
+}

package/src/components/modules/api/ui.ts

@@ -0,0 +1,36 @@
+import { Module } from '../../__module';
+import type { Ui, UiNodes } from '../../../../types/api';
+
+/**
+ * API module allowing to access some Blok UI elements
+ */
+export class UiAPI extends Module {
+  /**
+   * Available methods / getters
+   */
+  public get methods(): Ui {
+    return {
+      nodes: this.blokNodes,
+      /**
+       * There can be added some UI methods, like toggleThinMode() etc
+       */
+    };
+  }
+
+  /**
+   * Exported classes
+   */
+  private get blokNodes(): UiNodes {
+    return {
+      /**
+       * Top-level blok instance wrapper
+       */
+      wrapper: this.Blok.UI.nodes.wrapper,
+
+      /**
+       * Element that holds all the Blocks
+       */
+      redactor: this.Blok.UI.nodes.redactor,
+    };
+  }
+}