@jackuait/blok 0.4.1-beta.1 → 0.4.1-beta.11

package/src/components/modules/renderer.ts

@@ -0,0 +1,155 @@
+import { Module } from '../__module';
+import { log, logLabeled } from '../utils';
+import type { BlockId, BlockToolData, OutputBlockData } from '../../../types';
+import type { BlockToolAdapter } from '../tools/block';
+import type { StubData } from '../../tools/stub';
+import type { Block } from '../block';
+import {
+  analyzeDataFormat,
+  expandToHierarchical,
+  shouldExpandToHierarchical,
+  type DataFormatAnalysis,
+} from '../utils/data-model-transform';
+
+/**
+ * Module that responsible for rendering Blocks on blok initialization
+ */
+export class Renderer extends Module {
+  /**
+   * Stores the detected input data format for use during save
+   */
+  private detectedInputFormat: DataFormatAnalysis['format'] = 'flat';
+
+  /**
+   * Get the detected input format
+   */
+  public getDetectedInputFormat(): DataFormatAnalysis['format'] {
+    return this.detectedInputFormat;
+  }
+
+  /**
+   * Renders passed blocks as one batch
+   * @param blocksData - blocks to render
+   */
+  public render(blocksData: OutputBlockData[]): Promise<void> {
+    return new Promise((resolve) => {
+      const { Tools, BlockManager } = this.Blok;
+
+      if (blocksData.length === 0) {
+        BlockManager.insert();
+      } else {
+        // Analyze and potentially transform the input data
+        const dataModelConfig = this.config.dataModel || 'auto';
+        const analysis = analyzeDataFormat(blocksData);
+        this.detectedInputFormat = analysis.format;
+
+        // Transform to hierarchical if config requires it
+        const processedBlocks = shouldExpandToHierarchical(dataModelConfig, analysis.format)
+          ? expandToHierarchical(blocksData)
+          : blocksData;
+
+        /**
+         * Create Blocks instances
+         */
+        const blocks = processedBlocks.map((blockData: OutputBlockData) => {
+          const { tunes, id, parent, content } = blockData;
+          const originalTool = blockData.type;
+          const availabilityResult = (() => {
+            if (Tools.available.has(originalTool)) {
+              return {
+                tool: originalTool,
+                data: blockData.data,
+              };
+            }
+
+            logLabeled(`Tool «${originalTool}» is not found. Check 'tools' property at the Blok config.`, 'warn');
+
+            return {
+              tool: Tools.stubTool,
+              data: this.composeStubDataForTool(originalTool, blockData.data, id),
+            };
+          })();
+
+          const buildBlock = (tool: string, data: BlockToolData): Block => {
+            try {
+              return BlockManager.composeBlock({
+                id,
+                tool,
+                data,
+                tunes,
+                parentId: parent,
+                contentIds: content,
+              });
+            } catch (error) {
+              log(`Block «${tool}» skipped because of plugins error`, 'error', {
+                data,
+                error,
+              });
+
+              /**
+               * If tool throws an error during render, we should render stub instead of it
+               */
+              const stubData = this.composeStubDataForTool(tool, data, id);
+
+              return BlockManager.composeBlock({
+                id,
+                tool: Tools.stubTool,
+                data: stubData,
+                tunes,
+                parentId: parent,
+                contentIds: content,
+              });
+            }
+          };
+
+          return buildBlock(availabilityResult.tool, availabilityResult.data);
+        });
+
+        /**
+         * Insert batch of Blocks
+         */
+        BlockManager.insertMany(blocks);
+      }
+
+      /**
+       * Wait till browser will render inserted Blocks and resolve a promise
+       */
+      window.requestIdleCallback(() => {
+        resolve();
+      }, { timeout: 2000 });
+    });
+  }
+
+  /**
+   * Create data for the Stub Tool that will be used instead of unavailable tool
+   * @param tool - unavailable tool name to stub
+   * @param data - data of unavailable block
+   * @param [id] - id of unavailable block
+   */
+  private composeStubDataForTool(tool: string, data: BlockToolData, id?: BlockId): StubData {
+    const { Tools } = this.Blok;
+
+    const title = (() => {
+      if (!Tools.unavailable.has(tool)) {
+        return tool;
+      }
+
+      const toolboxSettings = (Tools.unavailable.get(tool) as BlockToolAdapter).toolbox;
+
+      if (toolboxSettings !== undefined && toolboxSettings[0].title !== undefined) {
+        return toolboxSettings[0].title;
+      }
+
+      return tool;
+    })();
+
+    return {
+      savedData: {
+        id,
+        type: tool,
+        data,
+      },
+      title,
+    };
+  }
+}

package/src/components/modules/saver.ts

@@ -0,0 +1,283 @@
+/**
+ * Blok Saver
+ * @module Saver
+ * @author Blok Team
+ * @version 2.0.0
+ */
+import { Module } from '../__module';
+import type { BlockToolData, OutputData, SanitizerConfig } from '../../../types';
+import type { SavedData, ValidatedData } from '../../../types/data-formats';
+import type { BlockTuneData } from '../../../types/block-tunes/block-tune-data';
+import type { Block } from '../block';
+import { getBlokVersion, isEmpty, isObject, log, logLabeled } from '../utils';
+import { sanitizeBlocks } from '../utils/sanitizer';
+import { collapseToLegacy, shouldCollapseToLegacy } from '../utils/data-model-transform';
+
+type SaverValidatedData = ValidatedData & {
+  tunes?: Record<string, BlockTuneData>;
+  /**
+   * Parent block id for hierarchical structure (Notion-like flat-with-references model)
+   */
+  parentId?: string | null;
+  /**
+   * Array of child block ids (Notion-like flat-with-references model)
+   */
+  contentIds?: string[];
+};
+
+type SanitizableBlockData = SaverValidatedData & Pick<SavedData, 'data' | 'tool'>;
+
+/**
+ * @classdesc This method reduces all Blocks asyncronically and calls Block's save method to extract data
+ * @typedef {Saver} Saver
+ * @property {Element} html - Blok HTML content
+ * @property {string} json - Blok JSON output
+ */
+export class Saver extends Module {
+  /**
+   * Stores the last error raised during save attempt
+   */
+  private lastSaveError?: unknown;
+
+  /**
+   * Composes new chain of Promises to fire them alternatelly
+   * @returns {OutputData | undefined}
+   */
+  public async save(): Promise<OutputData | undefined> {
+    const { BlockManager, Tools } = this.Blok;
+    const blocks = BlockManager.blocks;
+
+    /**
+     * If there is only one block and it is empty, we should return empty blocks array
+     */
+    if (blocks.length === 1 && blocks[0].isEmpty) {
+      return {
+        time: +new Date(),
+        blocks: [],
+        version: getBlokVersion(),
+      };
+    }
+
+    const chainData: Array<Promise<SaverValidatedData>> = blocks.map((block: Block) => {
+      return this.getSavedData(block);
+    });
+
+    this.lastSaveError = undefined;
+
+    try {
+      const extractedData = await Promise.all(chainData);
+      const sanitizedData = this.sanitizeExtractedData(
+        extractedData,
+        (name) => Tools.blockTools.get(name)?.sanitizeConfig,
+        this.config.sanitizer as SanitizerConfig
+      );
+
+      return this.makeOutput(sanitizedData);
+    } catch (error: unknown) {
+      this.lastSaveError = error;
+
+      const normalizedError = error instanceof Error ? error : new Error(String(error));
+
+      logLabeled(`Saving failed due to the Error %o`, 'error', normalizedError);
+
+      return undefined;
+    }
+  }
+
+  /**
+   * Saves and validates
+   * @param {Block} block - Blok's Tool
+   * @returns {ValidatedData} - Tool's validated data
+   */
+  private async getSavedData(block: Block): Promise<SaverValidatedData> {
+    const blockData = await block.save();
+    const toolName = block.name;
+    const normalizedData = blockData?.data !== undefined
+      ? blockData
+      : this.getPreservedSavedData(block);
+
+    if (normalizedData === undefined) {
+      return {
+        tool: toolName,
+        isValid: false,
+      };
+    }
+
+    const isValid = await block.validate(normalizedData.data);
+
+    return {
+      ...normalizedData,
+      isValid,
+      parentId: block.parentId,
+      contentIds: block.contentIds,
+    };
+  }
+
+  /**
+   * Creates output object with saved data, time and version of blok
+   * @param {ValidatedData} allExtractedData - data extracted from Blocks
+   * @returns {OutputData}
+   */
+  private makeOutput(allExtractedData: SaverValidatedData[]): OutputData {
+    const extractedBlocks: OutputData['blocks'] = [];
+
+    allExtractedData.forEach(({ id, tool, data, tunes, isValid, parentId, contentIds }) => {
+      if (!isValid) {
+        log(`Block «${tool}» skipped because saved data is invalid`);
+
+        return;
+      }
+
+      if (tool === undefined || data === undefined) {
+        log('Block skipped because saved data is missing required fields');
+
+        return;
+      }
+
+      /** If it was stub Block, get original data */
+      if (tool === this.Blok.Tools.stubTool && this.isStubSavedData(data)) {
+        extractedBlocks.push(data);
+
+        return;
+      }
+
+      if (tool === this.Blok.Tools.stubTool) {
+        log('Stub block data is malformed and was skipped');
+
+        return;
+      }
+
+      const isTunesEmpty = tunes === undefined || isEmpty(tunes);
+      const hasParent = parentId !== undefined && parentId !== null;
+      const hasContent = contentIds !== undefined && contentIds.length > 0;
+
+      const output: OutputData['blocks'][number] = {
+        id,
+        type: tool,
+        data,
+        ...!isTunesEmpty && {
+          tunes,
+        },
+        ...hasParent && {
+          parent: parentId,
+        },
+        ...hasContent && {
+          content: contentIds,
+        },
+      };
+
+      extractedBlocks.push(output);
+    });
+
+    // Apply data model transformation if needed
+    const dataModelConfig = this.config.dataModel || 'auto';
+    const detectedInputFormat = this.Blok.Renderer?.getDetectedInputFormat?.() ?? 'flat';
+
+    const finalBlocks = shouldCollapseToLegacy(dataModelConfig, detectedInputFormat)
+      ? collapseToLegacy(extractedBlocks)
+      : extractedBlocks;
+
+    return {
+      time: +new Date(),
+      blocks: finalBlocks,
+      version: getBlokVersion(),
+    };
+  }
+
+  /**
+   * Sanitizes extracted block data in-place
+   * @param extractedData - collection of saved block data
+   * @param getToolSanitizeConfig - resolver for tool-specific sanitize config
+   * @param globalSanitizer - global sanitizer config specified in blok settings
+   */
+  private sanitizeExtractedData(
+    extractedData: SaverValidatedData[],
+    getToolSanitizeConfig: (toolName: string) => SanitizerConfig | undefined,
+    globalSanitizer: SanitizerConfig
+  ): SaverValidatedData[] {
+    const blocksToSanitize: Array<{ index: number; data: SanitizableBlockData }> = [];
+
+    extractedData.forEach((blockData, index) => {
+      if (this.hasSanitizableData(blockData)) {
+        blocksToSanitize.push({
+          index,
+          data: blockData,
+        });
+      }
+    });
+
+    if (blocksToSanitize.length === 0) {
+      return extractedData;
+    }
+
+    const sanitizedBlocks = sanitizeBlocks(
+      blocksToSanitize.map(({ data }) => data),
+      getToolSanitizeConfig,
+      globalSanitizer
+    );
+
+    const updatedData = extractedData.map((blockData) => ({ ...blockData }));
+
+    blocksToSanitize.forEach(({ index }, sanitizedIndex) => {
+      const sanitized = sanitizedBlocks[sanitizedIndex];
+
+      updatedData[index] = {
+        ...updatedData[index],
+        data: sanitized.data,
+      };
+    });
+
+    return updatedData;
+  }
+
+  /**
+   * Checks whether block data contains fields required for sanitizing procedure
+   * @param blockData - data to check
+   */
+  private hasSanitizableData(blockData: SaverValidatedData): blockData is SanitizableBlockData {
+    return blockData.data !== undefined && typeof blockData.tool === 'string';
+  }
+
+  /**
+   * Check that stub data matches OutputBlockData format
+   * @param data - saved stub data that should represent original block payload
+   */
+  private isStubSavedData(data: BlockToolData): data is OutputData['blocks'][number] {
+    if (!isObject(data)) {
+      return false;
+    }
+
+    const candidate = data as Record<string, unknown>;
+
+    return typeof candidate.type === 'string' && candidate.data !== undefined;
+  }
+
+  /**
+   * Returns the last error raised during save attempt
+   */
+  public getLastSaveError(): unknown {
+    return this.lastSaveError;
+  }
+
+  /**
+   * Returns the last successfully extracted data for the provided block, if any.
+   * @param block - block whose preserved data should be returned
+   */
+  private getPreservedSavedData(block: Block): (SavedData & { tunes?: Record<string, BlockTuneData> }) | undefined {
+    const preservedData = block.preservedData;
+
+    if (isEmpty(preservedData)) {
+      return undefined;
+    }
+
+    const preservedTunes = block.preservedTunes;
+
+    return {
+      id: block.id,
+      tool: block.name,
+      data: preservedData,
+      ...( isEmpty(preservedTunes) ? {} : { tunes: preservedTunes }),
+      time: 0,
+    };
+  }
+}