@jackuait/blok 0.4.1 → 0.4.2

package/src/components/utils/announcer.ts

@@ -0,0 +1,205 @@
+/**
+ * @module Announcer
+ * @description Provides screen reader announcements via ARIA live regions
+ * Following WAI-ARIA best practices for dynamic content updates
+ */
+
+const ARIA_LIVE_REGION_ID = 'blok-announcer';
+
+/**
+ * Tailwind sr-only pattern for visually hiding content while keeping it accessible
+ */
+const SR_ONLY_CLASSES = [
+  'absolute',
+  'w-px',
+  'h-px',
+  'p-0',
+  '-m-px',
+  'overflow-hidden',
+  '[clip:rect(0,0,0,0)]',
+  'whitespace-nowrap',
+  'border-0',
+].join(' ');
+
+interface AnnouncerConfig {
+  /** Politeness level: 'polite' for non-critical, 'assertive' for important */
+  politeness?: 'polite' | 'assertive';
+  /** Clear announcement after this many milliseconds (default: 1000) */
+  clearAfter?: number;
+}
+
+/**
+ * Singleton class that manages an ARIA live region for screen reader announcements
+ * Supports multiple Blok instances on the same page via reference counting
+ */
+class Announcer {
+  /**
+   * Singleton instance
+   */
+  private static instance: Announcer | null = null;
+
+  /**
+   * Reference count for multi-instance support
+   * Tracks how many Blok instances are using this announcer
+   */
+  private static referenceCount = 0;
+
+  /**
+   * The ARIA live region element
+   */
+  private liveRegion: HTMLElement | null = null;
+
+  /**
+   * Timeout for clearing announcement
+   */
+  private clearTimeoutId: ReturnType<typeof setTimeout> | null = null;
+
+  /**
+   * Private constructor for singleton
+   */
+  private constructor() {
+    this.createLiveRegion();
+  }
+
+  /**
+   * Get singleton instance and increment reference count
+   */
+  public static getInstance(): Announcer {
+    if (!Announcer.instance) {
+      Announcer.instance = new Announcer();
+    }
+
+    return Announcer.instance;
+  }
+
+  /**
+   * Increment reference count when a Blok instance starts using the announcer
+   */
+  public static addReference(): void {
+    Announcer.referenceCount++;
+  }
+
+  /**
+   * Creates the ARIA live region element
+   * Uses sr-only pattern to hide from sighted users while remaining accessible
+   */
+  private createLiveRegion(): void {
+    // Check if already exists (multiple Blok instances on same page)
+    const existingRegion = document.getElementById(ARIA_LIVE_REGION_ID);
+
+    if (existingRegion) {
+      this.liveRegion = existingRegion;
+
+      return;
+    }
+
+    const region = document.createElement('div');
+
+    region.id = ARIA_LIVE_REGION_ID;
+    region.className = SR_ONLY_CLASSES;
+    region.setAttribute('role', 'status');
+    region.setAttribute('aria-live', 'polite');
+    region.setAttribute('aria-atomic', 'true');
+    region.setAttribute('data-blok-announcer', '');
+
+    document.body.appendChild(region);
+
+    this.liveRegion = region;
+  }
+
+  /**
+   * Announce a message to screen readers
+   * @param message - The message to announce
+   * @param config - Configuration options
+   */
+  public announce(message: string, config: AnnouncerConfig = {}): void {
+    const { politeness = 'polite', clearAfter = 1000 } = config;
+
+    // Ensure live region exists (defensive, should always exist after constructor)
+    if (!this.liveRegion) {
+      this.createLiveRegion();
+    }
+
+    // Guard against edge case where createLiveRegion fails
+    if (!this.liveRegion) {
+      return;
+    }
+
+    // Clear any pending timeout
+    if (this.clearTimeoutId !== null) {
+      clearTimeout(this.clearTimeoutId);
+    }
+
+    // Update politeness level
+    this.liveRegion.setAttribute('aria-live', politeness);
+
+    // Clear then set to ensure announcement triggers even if same message
+    this.liveRegion.textContent = '';
+
+    // Use requestAnimationFrame to ensure DOM update before setting new content
+    requestAnimationFrame(() => {
+      if (this.liveRegion) {
+        this.liveRegion.textContent = message;
+      }
+    });
+
+    // Clear after delay to prepare for next announcement
+    this.clearTimeoutId = setTimeout(() => {
+      if (this.liveRegion) {
+        this.liveRegion.textContent = '';
+      }
+    }, clearAfter);
+  }
+
+  /**
+   * Clean up the live region
+   * Only removes the DOM element when all references are released
+   */
+  public destroy(): void {
+    Announcer.referenceCount--;
+
+    // Only clean up when last reference is released
+    if (Announcer.referenceCount > 0) {
+      return;
+    }
+
+    if (this.clearTimeoutId !== null) {
+      clearTimeout(this.clearTimeoutId);
+      this.clearTimeoutId = null;
+    }
+
+    if (this.liveRegion) {
+      this.liveRegion.remove();
+      this.liveRegion = null;
+    }
+
+    Announcer.instance = null;
+  }
+}
+
+/**
+ * Announce a message to screen readers
+ * @param message - The message to announce
+ * @param config - Configuration options
+ */
+export const announce = (message: string, config?: AnnouncerConfig): void => {
+  Announcer.getInstance().announce(message, config);
+};
+
+/**
+ * Register a Blok instance as using the announcer
+ * Call this when a Blok instance is created
+ */
+export const registerAnnouncer = (): void => {
+  Announcer.addReference();
+  // Ensure instance is created
+  Announcer.getInstance();
+};
+
+/**
+ * Clean up the announcer and remove the live region
+ * Only removes the DOM element when all Blok instances have been destroyed
+ */
+export const destroyAnnouncer = (): void => {
+  Announcer.getInstance().destroy();
+};

package/src/components/utils/api.ts

@@ -0,0 +1,20 @@
+import type { BlockAPI } from '../../../types/api/block';
+import type { BlokModules } from '../../types-internal/blok-modules';
+import type { Block } from '../block';
+
+/**
+ * Returns Block instance by passed Block index or Block id
+ * @param attribute - either BlockAPI or Block id or Block index
+ * @param blok - Blok instance
+ */
+export const resolveBlock = (attribute: BlockAPI | BlockAPI['id'] | number, blok: BlokModules): Block | undefined => {
+  if (typeof attribute === 'number') {
+    return blok.BlockManager.getBlockByIndex(attribute);
+  }
+
+  if (typeof attribute === 'string') {
+    return blok.BlockManager.getBlockById(attribute);
+  }
+
+  return blok.BlockManager.getBlockById(attribute.id);
+};

package/src/components/utils/bem.ts

@@ -0,0 +1,26 @@
+const ELEMENT_DELIMITER = '__';
+const MODIFIER_DELIMITER = '--';
+
+/**
+ * Utility function that allows to construct class names from block and element names
+ * @example bem('blok-popover)() -> 'blok-popover'
+ * @example bem('blok-popover)('container') -> 'blok-popover__container'
+ * @example bem('blok-popover)('container', 'hidden') -> 'blok-popover__container--hidden'
+ * @example bem('blok-popover)(null, 'hidden') -> 'blok-popover--hidden'
+ * @param blockName - string with block name
+ */
+export const bem = (blockName: string) => {
+  /**
+   * @param elementName - string with element name
+   * @param modifier - modifier to be appended
+   */
+  return (elementName?: string | null, modifier?: string) => {
+    const className = [blockName, elementName]
+      .filter(x => !!x)
+      .join(ELEMENT_DELIMITER);
+
+    return [className, modifier]
+      .filter(x => !!x)
+      .join(MODIFIER_DELIMITER);
+  };
+};

package/src/components/utils/blocks.ts

@@ -0,0 +1,284 @@
+import type { BlockAPI, ToolConfig } from '../../../types';
+import type { ConversionConfig } from '../../../types/configs/conversion-config';
+import type { SavedData } from '../../../types/data-formats';
+import type { BlockToolData } from '../../../types/tools/block-tool-data';
+import type { Block } from '../block';
+import type { BlockToolAdapter } from '../tools/block';
+import { isFunction, isString, log, equals, isEmpty } from '../utils';
+import { isToolConvertable } from './tools';
+
+
+/**
+ * Check if block has valid conversion config for export or import.
+ * @param block - block to check
+ * @param direction - export for block to merge from, import for block to merge to
+ */
+export const isBlockConvertable = (block: Block, direction: 'export' | 'import'): boolean => {
+  return isToolConvertable(block.tool, direction);
+};
+
+/**
+ * Checks that all the properties of the first block data exist in second block data with the same values.
+ *
+ * Example:
+ *
+ * data1 = { level: 1 }
+ *
+ * data2 = {
+ * text: "Heading text",
+ * level: 1
+ * }
+ *
+ * isSameBlockData(data1, data2) => true
+ * @param data1 – first block data
+ * @param data2 – second block data
+ */
+export const isSameBlockData = (data1: BlockToolData, data2: BlockToolData): boolean => {
+  return Object.entries(data1).some((([propName, propValue]) => {
+    return data2[propName] && equals(data2[propName], propValue);
+  }));
+};
+
+/**
+ * Returns list of tools you can convert specified block to
+ * @param block - block to get conversion items for
+ * @param allBlockTools - all block tools available in the blok
+ */
+export const getConvertibleToolsForBlock = async (block: BlockAPI, allBlockTools: BlockToolAdapter[]): Promise<BlockToolAdapter[]> => {
+  const savedData = await block.save() as SavedData;
+  const blockData = savedData.data;
+
+  /**
+   * Checking that the block's tool has an «export» rule
+   */
+  const blockTool = allBlockTools.find((tool) => tool.name === block.name);
+
+  if (blockTool !== undefined && !isToolConvertable(blockTool, 'export')) {
+    return [];
+  }
+
+  return allBlockTools.reduce((result, tool) => {
+    /**
+     * Skip tools without «import» rule specified
+     */
+    if (!isToolConvertable(tool, 'import')) {
+      return result;
+    }
+
+    /**
+     * Skip tools that does not specify toolbox
+     */
+    if (tool.toolbox === undefined) {
+      return result;
+    }
+
+    /** Filter out invalid toolbox entries */
+    const actualToolboxItems = tool.toolbox.filter((toolboxItem) => {
+      /**
+       * Skip items that don't pass 'toolbox' property or do not have an icon
+       */
+      if (isEmpty(toolboxItem) || toolboxItem.icon === undefined) {
+        return false;
+      }
+
+      const hasToolboxData = toolboxItem.data !== undefined;
+
+      /**
+       * When a tool has several toolbox entries, we need to make sure we do not add
+       * toolbox item with the same data to the resulting array. This helps exclude duplicates
+       */
+      if (hasToolboxData && isSameBlockData(toolboxItem.data, blockData)) {
+        return false;
+      }
+
+      if (!hasToolboxData && tool.name === block.name) {
+        return false;
+      }
+
+      return true;
+    });
+
+    result.push({
+      ...tool,
+      toolbox: actualToolboxItems,
+    } as BlockToolAdapter);
+
+    return result;
+  }, [] as BlockToolAdapter[]);
+};
+
+
+/**
+ * Check if two blocks could be merged.
+ *
+ * We can merge two blocks if:
+ * - they have the same type
+ * - they have a merge function (.mergeable = true)
+ * - If they have valid conversions config
+ * @param targetBlock - block to merge to
+ * @param blockToMerge - block to merge from
+ */
+export const areBlocksMergeable = (targetBlock: Block, blockToMerge: Block): boolean => {
+  /**
+   * If target block has not 'merge' method, we can't merge blocks.
+   *
+   * Technically we can (through the conversion) but it will lead a target block delete and recreation, which is unexpected behavior.
+   */
+  if (!targetBlock.mergeable) {
+    return false;
+  }
+
+  /**
+   * Tool knows how to merge own data format
+   */
+  if (targetBlock.name === blockToMerge.name) {
+    return true;
+  }
+
+  /**
+   * We can merge blocks if they have valid conversion config
+   */
+  return isBlockConvertable(blockToMerge, 'export') && isBlockConvertable(targetBlock, 'import');
+};
+
+/**
+ * Returns list of tools that all specified blocks can be converted to.
+ * Only returns tools that are valid conversion targets for ALL blocks.
+ * @param blocks - array of blocks to get common conversion items for
+ * @param allBlockTools - all block tools available in the blok
+ */
+export const getConvertibleToolsForBlocks = async (blocks: BlockAPI[], allBlockTools: BlockToolAdapter[]): Promise<BlockToolAdapter[]> => {
+  if (blocks.length === 0) {
+    return [];
+  }
+
+  /**
+   * If only one block, use the single block function
+   */
+  if (blocks.length === 1) {
+    return getConvertibleToolsForBlock(blocks[0], allBlockTools);
+  }
+
+  /**
+   * Check that all blocks have export conversion config
+   */
+  for (const block of blocks) {
+    const blockTool = allBlockTools.find((tool) => tool.name === block.name);
+
+    if (blockTool !== undefined && !isToolConvertable(blockTool, 'export')) {
+      return [];
+    }
+  }
+
+  /**
+   * Get the set of tool names that all blocks currently use
+   */
+  const blockToolNames = new Set(blocks.map((block) => block.name));
+
+  /**
+   * Filter tools that have import conversion config and valid toolbox
+   */
+  return allBlockTools.reduce((result, tool) => {
+    /**
+     * Skip tools without «import» rule specified
+     */
+    if (!isToolConvertable(tool, 'import')) {
+      return result;
+    }
+
+    /**
+     * Skip tools that does not specify toolbox
+     */
+    if (tool.toolbox === undefined) {
+      return result;
+    }
+
+    /** Filter out invalid toolbox entries */
+    const actualToolboxItems = tool.toolbox.filter((toolboxItem) => {
+      /**
+       * Skip items that don't pass 'toolbox' property or do not have an icon
+       */
+      if (isEmpty(toolboxItem) || toolboxItem.icon === undefined) {
+        return false;
+      }
+
+      /**
+       * For multiple blocks, we skip the tool if ALL selected blocks are already of this type
+       * (with no toolbox data override)
+       */
+      const hasToolboxData = toolboxItem.data !== undefined;
+
+      if (!hasToolboxData && blockToolNames.size === 1 && blockToolNames.has(tool.name)) {
+        return false;
+      }
+
+      return true;
+    });
+
+    if (actualToolboxItems.length > 0) {
+      result.push({
+        ...tool,
+        toolbox: actualToolboxItems,
+      } as BlockToolAdapter);
+    }
+
+    return result;
+  }, [] as BlockToolAdapter[]);
+};
+
+/**
+ * Using conversionConfig, convert block data to string.
+ * @param blockData - block data to convert
+ * @param conversionConfig - tool's conversion config
+ */
+export const convertBlockDataToString = (blockData: BlockToolData, conversionConfig?: ConversionConfig ): string => {
+  const exportProp = conversionConfig?.export;
+
+  if (isFunction(exportProp)) {
+    return exportProp(blockData);
+  }
+
+  if (isString(exportProp)) {
+    return blockData[exportProp];
+  }
+
+  /**
+   * Tool developer provides 'export' property, but it is not correct. Warn him.
+   */
+  if (exportProp !== undefined) {
+    log('Conversion «export» property must be a string or function. ' +
+    'String means key of saved data object to export. Function should export processed string to export.');
+  }
+
+  return '';
+};
+
+/**
+ * Using conversionConfig, convert string to block data.
+ * @param stringToImport - string to convert
+ * @param conversionConfig - tool's conversion config
+ * @param targetToolConfig - target tool config, used in conversionConfig.import method
+ */
+export const convertStringToBlockData = (stringToImport: string, conversionConfig?: ConversionConfig, targetToolConfig?: ToolConfig): BlockToolData => {
+  const importProp = conversionConfig?.import;
+
+  if (isFunction(importProp)) {
+    return importProp(stringToImport, targetToolConfig);
+  }
+
+  if (isString(importProp)) {
+    return {
+      [importProp]: stringToImport,
+    };
+  }
+
+  /**
+   * Tool developer provides 'import' property, but it is not correct. Warn him.
+   */
+  if (importProp !== undefined) {
+    log('Conversion «import» property must be a string or function. ' +
+    'String means key of tool data to import. Function accepts a imported string and return composed tool data.');
+  }
+
+  return {};
+};