@wix/web5-core 1.56.0

package/dist/esm/markdownBlocks.js

@@ -0,0 +1,641 @@
+import { isHtmlComment } from './utils/nodeMatchers.js';
+import { parseHtmlComment, extractHtmlCommentValue } from './utils/htmlCommentParser.js';
+import { extractLinkMetadata } from './utils/entityLinkParser.js';
+
+/**
+ * Re-export BlockElement for convenience
+ */
+
+/**
+ * Internal type for block elements with optional metadata during processing
+ */
+
+/**
+ * Extract image metadata from an image AST node
+ * Derives the image type from web5:// protocol URLs
+ */
+function extractImageMetadata(node) {
+  const src = node.url;
+  if (!src) {
+    return undefined;
+  }
+  const meta = {
+    src
+  };
+  if (node.alt) {
+    meta.alt = node.alt;
+  }
+
+  // Derive type from web5:// protocol: web5://icon/dollar → type = "icon"
+  const web5Match = src.match(/^web5:\/\/([^/]+)/);
+  if (web5Match) {
+    meta.type = web5Match[1];
+  }
+  return meta;
+}
+
+/**
+ * Convert an array of markdown AST nodes to a list of enriched BlockElement types
+ * Each block element includes the AST node index it was extracted from
+ *
+ * @param nodes - Array of markdown AST nodes (RootContent[])
+ * @returns Array of EnrichedBlockElement types representing the structure of the markdown
+ *
+ * @example
+ * ```typescript
+ * const astNodes = parseMarkdown('# Title\n\nParagraph text');
+ * const blockElements = convertToBlockElements(astNodes);
+ * // Returns: [{ element: 'h1', astNodeIndex: 0 }, { element: 't', astNodeIndex: 1 }]
+ * ```
+ */
+export function convertToBlockElements(nodes) {
+  const result = [];
+  for (let astIndex = 0; astIndex < nodes.length; astIndex++) {
+    const node = nodes[astIndex];
+    const elements = convertNodeToBlockElementsWithMetadata(node);
+
+    // Each block element from this AST node maps to the same AST node index
+    for (const elementWithMeta of elements) {
+      const enrichedElement = {
+        element: elementWithMeta.element,
+        astNodeIndex: astIndex
+      };
+
+      // Extract HTML comment metadata if this is an html_comment element
+      if (elementWithMeta.element === 'html_comment' && node.type === 'html') {
+        const commentValue = extractHtmlCommentValue(node);
+        if (commentValue) {
+          const metadata = parseHtmlComment(commentValue);
+          if (Object.keys(metadata).length > 0) {
+            enrichedElement.htmlCommentMetadata = metadata;
+          }
+        }
+      }
+
+      // Add link metadata if present
+      if (elementWithMeta.linkMetadata) {
+        enrichedElement.linkMetadata = elementWithMeta.linkMetadata;
+      }
+
+      // Add image metadata if present
+      if (elementWithMeta.imageMetadata) {
+        enrichedElement.imageMetadata = elementWithMeta.imageMetadata;
+      }
+
+      // Add enriched list items if present (for attribute matching in list items)
+      if (elementWithMeta.listItemsBlockElements) {
+        enrichedElement.listItemsEnriched = elementWithMeta.listItemsBlockElements.map(itemElements => itemElements.map(el => ({
+          element: el.element,
+          astNodeIndex: astIndex,
+          ...(el.linkMetadata ? {
+            linkMetadata: el.linkMetadata
+          } : {}),
+          ...(el.imageMetadata ? {
+            imageMetadata: el.imageMetadata
+          } : {})
+        })));
+      }
+      result.push(enrichedElement);
+    }
+  }
+  return result;
+}
+
+/**
+ * Result type for converting AST nodes to block elements with AST node index mapping
+ */
+
+/**
+ * Convert an array of markdown AST nodes to block elements with AST node index mapping
+ *
+ * @param nodes - Array of markdown AST nodes (RootContent[])
+ * @returns Object containing block elements and mapping from block element index to AST node index
+ *
+ * @example
+ * ```typescript
+ * const astNodes = parseMarkdown('# Title\n\nParagraph text');
+ * const { blockElements, astNodeIndices } = convertToBlockElementsWithMapping(astNodes);
+ * // blockElements: ['h1', 't']
+ * // astNodeIndices: [0, 1] // h1 from node 0, t from node 1
+ * ```
+ */
+export function convertToBlockElementsWithMapping(nodes) {
+  const blockElements = [];
+  const astNodeIndices = [];
+  for (let astIndex = 0; astIndex < nodes.length; astIndex++) {
+    const node = nodes[astIndex];
+    const elements = convertNodeToBlockElements(node);
+
+    // Each block element from this AST node maps to the same AST node index
+    for (const element of elements) {
+      blockElements.push(element);
+      astNodeIndices.push(astIndex);
+    }
+  }
+  return {
+    blockElements,
+    astNodeIndices
+  };
+}
+
+/**
+ * Convert a single AST node to its corresponding BlockElement type(s)
+ * Unwraps paragraphs to process their children instead of treating paragraph as a block element
+ *
+ * @param node - A single markdown AST node
+ * @returns Array of BlockElement types (can be empty if node doesn't map to block elements)
+ */
+function convertNodeToBlockElements(node) {
+  return convertNodeToBlockElementsWithMetadata(node).map(e => e.element);
+}
+
+/**
+ * Convert a single AST node to its corresponding BlockElement type(s) with metadata
+ * Unwraps paragraphs to process their children instead of treating paragraph as a block element
+ *
+ * @param node - A single markdown AST node
+ * @returns Array of BlockElementWithMetadata (can be empty if node doesn't map to block elements)
+ */
+function convertNodeToBlockElementsWithMetadata(node) {
+  switch (node.type) {
+    case 'heading':
+      // Map heading depth to h1-h6
+      switch (node.depth) {
+        case 1:
+          return [{
+            element: 'h1'
+          }];
+        case 2:
+          return [{
+            element: 'h2'
+          }];
+        case 3:
+          return [{
+            element: 'h3'
+          }];
+        case 4:
+          return [{
+            element: 'h4'
+          }];
+        case 5:
+          return [{
+            element: 'h5'
+          }];
+        case 6:
+          return [{
+            element: 'h6'
+          }];
+        default:
+          // Fallback for unexpected depths (shouldn't happen in standard markdown)
+          return [];
+      }
+    case 'paragraph':
+      // Unwrap paragraph: recursively process its children (inline nodes)
+      return convertParagraphChildrenWithMetadata(node);
+    case 'list':
+      {
+        // Process list items recursively and convert to block elements
+        const {
+          elements,
+          enrichedItems
+        } = convertListItemsWithMetadata(node);
+        return elements.map(e => ({
+          element: e,
+          ...(enrichedItems.length > 0 ? {
+            listItemsBlockElements: enrichedItems
+          } : {})
+        }));
+      }
+    case 'image':
+      {
+        const src = node.url || '';
+        if (/^web5:\/\/icon\//.test(src)) {
+          return [{
+            element: 'icon'
+          }];
+        }
+        const imgMeta = extractImageMetadata(node);
+        return [{
+          element: 'image',
+          ...(imgMeta ? {
+            imageMetadata: imgMeta
+          } : {})
+        }];
+      }
+    case 'table':
+      return [{
+        element: 'table'
+      }];
+    case 'blockquote':
+      return [{
+        element: 'callout'
+      }];
+    case 'html':
+      // Check if HTML node is a comment
+      if (isHtmlComment(node)) {
+        return [{
+          element: 'html_comment'
+        }];
+      }
+      // HTML nodes that aren't comments don't map to block elements
+      return [];
+    case 'thematicBreak':
+      return [{
+        element: 'thematicBreak'
+      }];
+    default:
+      // Other node types (e.g., 'code', 'definition', etc.)
+      // don't map to BlockElement types
+      return [];
+  }
+}
+
+/**
+ * Recursively convert paragraph children (inline nodes) to block elements with metadata
+ * Processes inline nodes like links, text, images, etc. and converts them to block elements
+ *
+ * @param paragraph - A paragraph node
+ * @returns Array of BlockElementWithMetadata representing the inline content
+ */
+function convertParagraphChildrenWithMetadata(paragraph) {
+  if (!paragraph.children || paragraph.children.length === 0) {
+    return [];
+  }
+
+  // Process all children and merge consecutive text elements
+  const result = [];
+  let hasTextInCurrentSegment = false;
+  for (const child of paragraph.children) {
+    const elements = convertInlineNodeToBlockElementsWithMetadata(child);
+    for (const elementWithMeta of elements) {
+      // Links, images, and icons break text segments
+      if (elementWithMeta.element === 'link' || elementWithMeta.element === 'image' || elementWithMeta.element === 'icon') {
+        // Flush current text segment if any
+        if (hasTextInCurrentSegment) {
+          result.push({
+            element: 't'
+          });
+          hasTextInCurrentSegment = false;
+        }
+        result.push(elementWithMeta);
+      } else if (elementWithMeta.element === 't') {
+        // Accumulate text
+        hasTextInCurrentSegment = true;
+      } else {
+        // Other elements
+        if (hasTextInCurrentSegment) {
+          result.push({
+            element: 't'
+          });
+          hasTextInCurrentSegment = false;
+        }
+        result.push(elementWithMeta);
+      }
+    }
+  }
+
+  // Flush final text segment
+  if (hasTextInCurrentSegment) {
+    result.push({
+      element: 't'
+    });
+  }
+
+  // If paragraph only contains an image or icon (no text or links), return just it (preserving metadata)
+  if (result.length === 1 && (result[0].element === 'image' || result[0].element === 'icon')) {
+    return [result[0]];
+  }
+  return result;
+}
+
+/**
+ * Convert an inline node to block elements
+ * Handles inline nodes like text, links, strong, emphasis, etc.
+ *
+ * @param node - An inline AST node
+ * @returns Array of BlockElement types
+ */
+function convertInlineNodeToBlockElements(node) {
+  return convertInlineNodeToBlockElementsWithMetadata(node).map(e => e.element);
+}
+
+/**
+ * Convert an inline node to block elements with metadata
+ * Handles inline nodes like text, links, strong, emphasis, etc.
+ *
+ * @param node - An inline AST node
+ * @returns Array of BlockElementWithMetadata
+ */
+function convertInlineNodeToBlockElementsWithMetadata(node) {
+  var _node$value;
+  switch (node.type) {
+    case 'link':
+      {
+        const linkMeta = extractLinkMetadata(node);
+        // Drop links whose href is missing or whitespace-only. Such links
+        // cannot be navigated to and would otherwise break section patterns
+        // that require typed link attributes (e.g. `link[entityType]`).
+        if (!linkMeta) {
+          return [];
+        }
+        return [{
+          element: 'link',
+          linkMetadata: linkMeta
+        }];
+      }
+    case 'text':
+      // Text nodes become 't' (text) block elements
+      // Only include non-empty text (after trimming)
+      const trimmedValue = ((_node$value = node.value) == null ? void 0 : _node$value.trim()) || '';
+      return trimmedValue ? [{
+        element: 't'
+      }] : [];
+    case 'image':
+      {
+        const imgSrc = node.url || '';
+        if (/^web5:\/\/icon\//.test(imgSrc)) {
+          return [{
+            element: 'icon'
+          }];
+        }
+        const imageMeta = extractImageMetadata(node);
+        return [{
+          element: 'image',
+          ...(imageMeta ? {
+            imageMetadata: imageMeta
+          } : {})
+        }];
+      }
+    case 'strong':
+    case 'emphasis':
+    case 'inlineCode':
+    case 'delete':
+    case 'break':
+      // These inline formatting nodes are treated as text
+      // Recursively process their children if they have any
+      if (node.children && node.children.length > 0) {
+        return node.children.flatMap(child => convertInlineNodeToBlockElementsWithMetadata(child));
+      }
+      return [{
+        element: 't'
+      }];
+    default:
+      // For other inline node types, recursively process children if available
+      if (node.children && node.children.length > 0) {
+        return node.children.flatMap(child => convertInlineNodeToBlockElementsWithMetadata(child));
+      }
+      return [];
+  }
+}
+
+/**
+ * Recursively convert list items to block elements with metadata
+ * Returns both the pattern string and enriched items preserving link metadata
+ *
+ * @param list - A list node
+ * @returns Object with pattern string elements and enriched items
+ */
+function convertListItemsWithMetadata(list) {
+  const itemElements = [];
+  const enrichedItems = [];
+  for (const item of list.children) {
+    const itemBlocks = convertListItemToBlockElements(item);
+    const enrichedBlocks = convertListItemToBlockElementsEnriched(item);
+    // Drop items that produce no block elements (e.g. an item whose only
+    // content was a `[label]()` empty-href link). The pattern matcher's
+    // `parseListFromElement` already filters empty items from the string
+    // signature, so keeping them in `enrichedItems` would misalign indices.
+    if (itemBlocks.length === 0 && enrichedBlocks.length === 0) {
+      continue;
+    }
+    itemElements.push(itemBlocks);
+    enrichedItems.push(enrichedBlocks);
+  }
+  const itemsPattern = itemElements.map(item => `[${item.join(', ')}]`).join(', ');
+  return {
+    elements: [`list{${itemsPattern}}`],
+    enrichedItems
+  };
+}
+
+/**
+ * Convert a list item to block elements with text splitting for separators/bold
+ *
+ * @param item - A list item node
+ * @returns Array of BlockElement strings with metadata
+ */
+function convertListItemToBlockElements(item) {
+  if (!item.children || item.children.length === 0) {
+    return [];
+  }
+  const result = [];
+  for (const child of item.children) {
+    if (child.type === 'paragraph') {
+      result.push(...convertParagraphWithContext(child));
+    } else {
+      result.push(...convertNodeToBlockElements(child));
+    }
+  }
+  return result;
+}
+
+/**
+ * Convert a list item to block elements with metadata preserving link information
+ */
+function convertListItemToBlockElementsEnriched(item) {
+  if (!item.children || item.children.length === 0) {
+    return [];
+  }
+  const result = [];
+  for (const child of item.children) {
+    if (child.type === 'paragraph') {
+      result.push(...convertParagraphWithContextEnriched(child));
+    } else {
+      result.push(...convertNodeToBlockElementsWithMetadata(child));
+    }
+  }
+  return result;
+}
+
+/**
+ * Convert paragraph children with text splitting detection for list items,
+ * preserving link metadata
+ */
+function convertParagraphWithContextEnriched(paragraph) {
+  var _paragraph$children;
+  if (!((_paragraph$children = paragraph.children) != null && _paragraph$children.length)) {
+    return [];
+  }
+
+  // Check for separator and meaningful text after
+  let hasSeparatorWithText = false;
+  for (const child of paragraph.children) {
+    if (child.type === 'text' && (child.value.includes(': ') || child.value.includes('- '))) {
+      const parts = child.value.split(/[:-]\s/);
+      if (parts.length > 1) {
+        const afterSep = parts.slice(1).join('').replace(/[•\s]/g, '');
+        if (afterSep.length > 0) {
+          hasSeparatorWithText = true;
+          break;
+        }
+      }
+    }
+  }
+
+  // Process children and merge consecutive text elements
+  const result = [];
+  let hasTextInCurrentSegment = false;
+  let textSegmentStartsWithBold = false;
+  let isFirstTextSegment = true;
+  for (const child of paragraph.children) {
+    const elements = convertInlineNodeToBlockElementsWithMetadata(child);
+    for (const elementWithMeta of elements) {
+      // Links, images, and icons break text segments
+      if (elementWithMeta.element === 'link' || elementWithMeta.element === 'image' || elementWithMeta.element === 'icon') {
+        // Flush current text segment if any
+        if (hasTextInCurrentSegment) {
+          if (isFirstTextSegment && (textSegmentStartsWithBold || hasSeparatorWithText)) {
+            result.push({
+              element: 't'
+            }, {
+              element: 't'
+            });
+          } else {
+            result.push({
+              element: 't'
+            });
+          }
+          hasTextInCurrentSegment = false;
+          textSegmentStartsWithBold = false;
+          isFirstTextSegment = false;
+        }
+        result.push(elementWithMeta);
+      } else if (elementWithMeta.element === 't') {
+        // Mark if this text segment starts with bold
+        if (!hasTextInCurrentSegment) {
+          textSegmentStartsWithBold = child.type === 'strong';
+        }
+        // Accumulate text
+        hasTextInCurrentSegment = true;
+      } else {
+        // Other elements
+        if (hasTextInCurrentSegment) {
+          if (isFirstTextSegment && (textSegmentStartsWithBold || hasSeparatorWithText)) {
+            result.push({
+              element: 't'
+            }, {
+              element: 't'
+            });
+          } else {
+            result.push({
+              element: 't'
+            });
+          }
+          hasTextInCurrentSegment = false;
+          textSegmentStartsWithBold = false;
+          isFirstTextSegment = false;
+        }
+        result.push(elementWithMeta);
+      }
+    }
+  }
+
+  // Flush final text segment
+  if (hasTextInCurrentSegment) {
+    if (isFirstTextSegment && (textSegmentStartsWithBold || hasSeparatorWithText)) {
+      result.push({
+        element: 't'
+      }, {
+        element: 't'
+      });
+    } else {
+      result.push({
+        element: 't'
+      });
+    }
+  }
+  return result;
+}
+
+/**
+ * Convert paragraph children with text splitting detection for list items
+ */
+function convertParagraphWithContext(paragraph) {
+  var _paragraph$children2;
+  if (!((_paragraph$children2 = paragraph.children) != null && _paragraph$children2.length)) {
+    return [];
+  }
+
+  // Check for separator and meaningful text after
+  let hasSeparatorWithText = false;
+  for (const child of paragraph.children) {
+    if (child.type === 'text' && (child.value.includes(': ') || child.value.includes('- '))) {
+      const parts = child.value.split(/[:-]\s/);
+      if (parts.length > 1) {
+        const afterSep = parts.slice(1).join('').replace(/[•\s]/g, '');
+        if (afterSep.length > 0) {
+          hasSeparatorWithText = true;
+          break;
+        }
+      }
+    }
+  }
+
+  // Process children and merge consecutive text elements
+  const result = [];
+  let hasTextInCurrentSegment = false;
+  let textSegmentStartsWithBold = false;
+  let isFirstTextSegment = true;
+  for (const child of paragraph.children) {
+    const elements = convertInlineNodeToBlockElements(child);
+    for (const element of elements) {
+      // Links, images, and icons break text segments
+      if (element === 'link' || element === 'image' || element === 'icon') {
+        // Flush current text segment if any
+        if (hasTextInCurrentSegment) {
+          if (isFirstTextSegment && (textSegmentStartsWithBold || hasSeparatorWithText)) {
+            result.push('t', 't');
+          } else {
+            result.push('t');
+          }
+          hasTextInCurrentSegment = false;
+          textSegmentStartsWithBold = false;
+          isFirstTextSegment = false;
+        }
+        result.push(element);
+      } else if (element === 't') {
+        // Mark if this text segment starts with bold
+        if (!hasTextInCurrentSegment) {
+          // Check if this is start of a new segment with bold
+          textSegmentStartsWithBold = child.type === 'strong';
+        }
+        // Accumulate text
+        hasTextInCurrentSegment = true;
+      } else {
+        // Other elements (shouldn't happen often)
+        if (hasTextInCurrentSegment) {
+          if (isFirstTextSegment && (textSegmentStartsWithBold || hasSeparatorWithText)) {
+            result.push('t', 't');
+          } else {
+            result.push('t');
+          }
+          hasTextInCurrentSegment = false;
+          textSegmentStartsWithBold = false;
+          isFirstTextSegment = false;
+        }
+        result.push(element);
+      }
+    }
+  }
+
+  // Flush final text segment
+  if (hasTextInCurrentSegment) {
+    if (isFirstTextSegment && (textSegmentStartsWithBold || hasSeparatorWithText)) {
+      result.push('t', 't');
+    } else {
+      result.push('t');
+    }
+  }
+  return result;
+}
+//# sourceMappingURL=markdownBlocks.js.map