@jacobbubu/md-to-lark 1.5.1 → 1.7.0

package/dist/pipeline/hast-to-last.js

@@ -1,6 +1,7 @@
 import { toString } from 'hast-util-to-string';
 import { createDefaultImagePayload } from '../last/image-defaults.js';
 import { LAST_TEXTUAL_BLOCK_TYPE_SET } from '../last/textual-block-types.js';
+import { parseDirectiveWidth } from './markdown/md-to-semantic-hast.js';
 const BLOCK_CONTAINER_TAGS = new Set([
     'article',
     'section',
@@ -11,11 +12,15 @@ const BLOCK_CONTAINER_TAGS = new Set([
     'footer',
 ]);
 const DEFAULT_ALIGN = 'left';
-function createContext() {
+function createContext(options = {}) {
     return {
         blocks: {},
         blockCounter: 1,
         inlineCounter: 1,
+        imageSizeContext: options.imageSizeContext ?? {},
+        warnedImageSizeKeys: new Set(),
+        semanticTarget: options.semanticTarget ?? {},
+        ...(options.imageSizeResolver ? { imageSizeResolver: options.imageSizeResolver } : {}),
     };
 }
 function nextBlockId(ctx) {
@@ -145,9 +150,86 @@ function createDividerBlock(ctx, parentId) {
     });
     return blockId;
 }
-function createImageBlock(ctx, parentId, sourceUrl, alt = null) {
+function warnInvalidImageDisplaySize(ctx, key, message) {
+    if (ctx.warnedImageSizeKeys.has(key))
+        return;
+    ctx.warnedImageSizeKeys.add(key);
+    console.warn(`[md-to-lark] ${message}`);
+}
+function buildImageSizeResolverContext(ctx, image) {
+    const context = {};
+    if (ctx.imageSizeContext.inputPath) {
+        context.inputPath = ctx.imageSizeContext.inputPath;
+    }
+    if (ctx.imageSizeContext.resourceBaseDir) {
+        context.resourceBaseDir = ctx.imageSizeContext.resourceBaseDir;
+    }
+    if (image.alt) {
+        context.alt = image.alt;
+    }
+    if (image.title) {
+        context.title = image.title;
+    }
+    return context;
+}
+function toPositiveRoundedWidth(value, maximum = 1000) {
+    if (!Number.isFinite(value) || value <= 0)
+        return undefined;
+    return Math.min(maximum, Math.max(1, Math.round(value)));
+}
+function applyImageDisplaySize(ctx, image, block) {
+    if (!ctx.imageSizeResolver || !image.sourceUrl) {
+        return false;
+    }
+    const size = ctx.imageSizeResolver(image.sourceUrl, buildImageSizeResolverContext(ctx, image));
+    if (!size) {
+        return false;
+    }
+    const applyAspectRatio = () => {
+        if (typeof size.aspectRatio === 'number' &&
+            Number.isFinite(size.aspectRatio) &&
+            size.aspectRatio > 0 &&
+            typeof block.payload.width === 'number') {
+            block.payload.height = Math.max(1, Math.round(block.payload.width / size.aspectRatio));
+        }
+    };
+    const hasWidthRatio = typeof size.widthRatio === 'number';
+    if (hasWidthRatio) {
+        const ratio = size.widthRatio;
+        if (Number.isFinite(ratio) && ratio > 0 && ratio <= 1) {
+            const baseWidth = block.payload.width ??
+                createDefaultImagePayload(block.parentId ? ctx.blocks[block.parentId]?.type : undefined).width ??
+                0;
+            const width = toPositiveRoundedWidth(baseWidth * ratio);
+            if (width !== undefined) {
+                block.payload.width = width;
+                applyAspectRatio();
+            }
+            return true;
+        }
+        warnInvalidImageDisplaySize(ctx, `widthRatio:${image.sourceUrl}:${String(size.widthRatio)}`, `Ignoring invalid image widthRatio for ${image.sourceUrl}: ${String(size.widthRatio)}. Expected 0 < widthRatio <= 1.`);
+    }
+    if (typeof size.widthPx === 'number') {
+        const maximum = createDefaultImagePayload(block.parentId ? ctx.blocks[block.parentId]?.type : undefined).width ?? 1000;
+        const width = toPositiveRoundedWidth(size.widthPx, maximum);
+        if (width !== undefined) {
+            block.payload.width = width;
+            applyAspectRatio();
+            return true;
+        }
+        warnInvalidImageDisplaySize(ctx, `widthPx:${image.sourceUrl}:${String(size.widthPx)}`, `Ignoring invalid image widthPx for ${image.sourceUrl}: ${String(size.widthPx)}. Expected widthPx > 0.`);
+    }
+    return false;
+}
+function createImageBlock(ctx, parentId, sourceUrl, alt = null, title = null, linkHref = null, displayOverride) {
     const blockId = nextBlockId(ctx);
     const parentBlock = ctx.blocks[parentId];
+    const image = {
+        sourceUrl,
+        alt,
+        title,
+        linkHref,
+    };
     const blockBase = {
         id: blockId,
         type: 'image',
@@ -162,12 +244,90 @@ function createImageBlock(ctx, parentId, sourceUrl, alt = null) {
     if (alt) {
         selectorAttrs.alt = alt;
     }
+    if (title) {
+        selectorAttrs.title = title;
+    }
+    if (linkHref) {
+        selectorAttrs.linkHref = linkHref;
+    }
     if (Object.keys(selectorAttrs).length > 0) {
         blockBase.selector = { attrs: selectorAttrs };
     }
+    const resolverMatched = applyImageDisplaySize(ctx, image, blockBase);
+    const shouldApplyOverride = Boolean(displayOverride && (!displayOverride.fallback || !resolverMatched));
+    if (shouldApplyOverride && displayOverride?.widthRatio !== undefined) {
+        const ratio = displayOverride.widthRatio;
+        if (Number.isFinite(ratio) && ratio > 0 && ratio <= 1) {
+            const baseWidth = createDefaultImagePayload(parentBlock?.type).width ?? blockBase.payload.width ?? 0;
+            blockBase.payload.width = Math.max(1, Math.round(baseWidth * ratio));
+        }
+    }
+    else if (shouldApplyOverride && displayOverride?.widthPx !== undefined && displayOverride.widthPx > 0) {
+        const maximum = createDefaultImagePayload(parentBlock?.type).width ?? 1000;
+        blockBase.payload.width = Math.min(maximum, Math.max(1, Math.round(displayOverride.widthPx)));
+    }
+    if (shouldApplyOverride && displayOverride?.aspectRatio && blockBase.payload.width) {
+        blockBase.payload.height = Math.max(1, Math.round(blockBase.payload.width / displayOverride.aspectRatio));
+    }
+    if (displayOverride?.align)
+        blockBase.payload.align = displayOverride.align;
     addBlock(ctx, blockBase);
     return blockId;
 }
+function attachSemanticMeta(ctx, blockId, role, semanticId) {
+    const block = ctx.blocks[blockId];
+    if (!block)
+        return;
+    block.selector = {
+        ...(block.selector ?? {}),
+        labels: [...(block.selector?.labels ?? []), role],
+        attrs: {
+            ...(block.selector?.attrs ?? {}),
+            semanticRole: role,
+            ...(semanticId ? { semanticId } : {}),
+        },
+    };
+}
+function normalizeCalloutColor(value) {
+    return value?.trim().toLowerCase().replaceAll('-', '_') || undefined;
+}
+function calloutStyleForElement(element, footnote) {
+    const target = footnote ? undefined : getStringProp(element, 'type');
+    const defaults = {
+        note: { backgroundColor: 'light_gray', borderColor: 'gray' },
+        info: { backgroundColor: 'light_blue', borderColor: 'blue' },
+        tip: { backgroundColor: 'light_green', borderColor: 'green' },
+        warning: { backgroundColor: 'light_yellow', borderColor: 'yellow' },
+        danger: { backgroundColor: 'light_red', borderColor: 'red' },
+        important: { backgroundColor: 'light_purple', borderColor: 'purple' },
+    };
+    const style = defaults[target ?? 'note'] ?? defaults.note;
+    return {
+        backgroundColor: style.backgroundColor,
+        borderColor: style.borderColor,
+    };
+}
+function createCalloutBlock(ctx, parentId, element, footnote) {
+    const blockId = nextBlockId(ctx);
+    const base = calloutStyleForElement(element, footnote);
+    const footnoteTarget = ctx.semanticTarget.footnotes;
+    const backgroundColor = footnote ? normalizeCalloutColor(footnoteTarget?.background_color ?? null) : undefined;
+    const borderColor = footnote ? normalizeCalloutColor(footnoteTarget?.border_color ?? null) : undefined;
+    addBlock(ctx, {
+        id: blockId,
+        type: 'callout',
+        parentId,
+        children: [],
+        payload: {
+            ...base,
+            ...(backgroundColor ? { backgroundColor: backgroundColor } : {}),
+            ...(borderColor ? { borderColor: borderColor } : {}),
+            ...(footnoteTarget?.icon ? { emojiId: footnoteTarget.icon } : {}),
+        },
+    });
+    attachSemanticMeta(ctx, blockId, footnote ? 'footnote' : 'callout', getStringProp(element, 'semanticId') ?? undefined);
+    return blockId;
+}
 function createIframeBlock(ctx, parentId, url, iframeType) {
     const blockId = nextBlockId(ctx);
     addBlock(ctx, {
@@ -351,7 +511,7 @@ function parseInlineNodes(ctx, nodes, marks = createDefaultMarks()) {
         if (node.tagName === 'u') {
             nextMarks.underline = true;
         }
-        if (node.tagName === 'a') {
+        if (node.tagName === 'a' || node.tagName === 'm2l-footnote-reference') {
             const href = getStringProp(node, 'href');
             nextMarks.link = href ? { url: href } : null;
         }
@@ -370,17 +530,21 @@ function extractImageSourceFromElement(element) {
         return {
             sourceUrl: getStringProp(element, 'src'),
             alt: getStringProp(element, 'alt'),
+            title: getStringProp(element, 'title'),
+            linkHref: null,
         };
     }
     if (element.tagName !== 'a')
         return null;
+    const href = getStringProp(element, 'href');
     const meaningfulChildren = getMeaningfulChildren(getChildren(element));
     if (meaningfulChildren.length !== 1)
         return null;
     const only = meaningfulChildren[0];
     if (!only || !isElement(only))
         return null;
-    return extractImageSourceFromElement(only);
+    const imageSource = extractImageSourceFromElement(only);
+    return imageSource ? { ...imageSource, linkHref: href } : null;
 }
 function findStandaloneImageInParagraph(paragraph) {
     const meaningfulChildren = getMeaningfulChildren(getChildren(paragraph));
@@ -692,7 +856,7 @@ function convertTable(ctx, table, parentId) {
             const cellBlock = ctx.blocks[cellId];
             const richItem = cell ? findStandaloneRichItemInTableCell(cell) : null;
             if (cellBlock?.type === 'table_cell' && richItem?.kind === 'image') {
-                const imageId = createImageBlock(ctx, cellId, richItem.sourceUrl, richItem.alt);
+                const imageId = createImageBlock(ctx, cellId, richItem.sourceUrl, richItem.alt, richItem.title, richItem.linkHref);
                 cellBlock.children = [imageId];
                 cells.push(cellId);
                 continue;
@@ -764,7 +928,9 @@ function hasNonWhitespaceInline(inlines) {
 function convertParagraph(ctx, paragraph, parentId) {
     const standaloneImage = findStandaloneImageInParagraph(paragraph);
     if (standaloneImage?.sourceUrl) {
-        return [createImageBlock(ctx, parentId, standaloneImage.sourceUrl, standaloneImage.alt)];
+        return [
+            createImageBlock(ctx, parentId, standaloneImage.sourceUrl, standaloneImage.alt, standaloneImage.title, standaloneImage.linkHref),
+        ];
     }
     const standaloneIframe = findStandaloneIframePayloadInParagraph(paragraph);
     if (standaloneIframe) {
@@ -785,7 +951,7 @@ function convertParagraph(ctx, paragraph, parentId) {
         const image = isElement(child) ? extractImageSourceFromElement(child) : null;
         if (image?.sourceUrl) {
             flushText();
-            ids.push(createImageBlock(ctx, parentId, image.sourceUrl, image.alt));
+            ids.push(createImageBlock(ctx, parentId, image.sourceUrl, image.alt, image.title, image.linkHref));
             continue;
         }
         pendingInlineNodes.push(child);
@@ -796,6 +962,189 @@ function convertParagraph(ctx, paragraph, parentId) {
     }
     return [createTextualBlock(ctx, 'text', parentId, parseInlineNodes(ctx, getChildren(paragraph)))];
 }
+function collectSemanticImages(element) {
+    const images = [];
+    const visit = (node) => {
+        if (!isElement(node))
+            return;
+        const image = extractImageSourceFromElement(node);
+        if (image?.sourceUrl) {
+            images.push(image);
+            return;
+        }
+        for (const child of getChildren(node))
+            visit(child);
+    };
+    for (const child of getChildren(element))
+        visit(child);
+    return images;
+}
+function findDirectSemanticChild(element, tagName) {
+    return getChildren(element).find((child) => isElement(child) && child.tagName === tagName);
+}
+function createSemanticTextBlock(ctx, element, parentId, role, semanticId) {
+    const blockId = createTextualBlock(ctx, 'text', parentId, parseInlineNodes(ctx, getChildren(element)));
+    attachSemanticMeta(ctx, blockId, role, semanticId);
+    return blockId;
+}
+function parseSemanticAlign(element) {
+    return parseAlignValue(getStringProp(element, 'align'));
+}
+function semanticAnnotationIds(ctx, wrapper, parentId, semanticId) {
+    const result = {};
+    for (const role of ['caption', 'note', 'source']) {
+        const element = findDirectSemanticChild(wrapper, `m2l-${role}`);
+        if (element)
+            result[role] = createSemanticTextBlock(ctx, element, parentId, role, semanticId);
+    }
+    return result;
+}
+function convertSemanticFigure(ctx, figure, parentId) {
+    const semanticId = getStringProp(figure, 'semanticId') ?? undefined;
+    const display = parseDirectiveWidth(getStringProp(figure, 'width') ?? '');
+    const fallbackRatio = ctx.semanticTarget.figures?.default_width_ratio;
+    const effectiveDisplay = display ??
+        (typeof fallbackRatio === 'number' && fallbackRatio > 0 && fallbackRatio <= 1
+            ? { widthRatio: fallbackRatio, fallback: true }
+            : undefined);
+    const align = parseSemanticAlign(figure);
+    const imageIds = collectSemanticImages(figure).map((image) => {
+        const imageId = createImageBlock(ctx, parentId, image.sourceUrl, image.alt, image.title, image.linkHref, {
+            ...(effectiveDisplay ?? {}),
+            ...(align ? { align } : {}),
+        });
+        attachSemanticMeta(ctx, imageId, 'figure-image', semanticId);
+        return imageId;
+    });
+    const annotations = semanticAnnotationIds(ctx, figure, parentId, semanticId);
+    const target = ctx.semanticTarget.figures;
+    const ids = [];
+    if (target?.caption_position === 'above' && annotations.caption)
+        ids.push(annotations.caption);
+    if (target?.source_position === 'above' && annotations.source)
+        ids.push(annotations.source);
+    if (target?.note_position === 'above' && annotations.note)
+        ids.push(annotations.note);
+    ids.push(...imageIds);
+    if (target?.caption_position !== 'above' && annotations.caption)
+        ids.push(annotations.caption);
+    if (target?.source_position === 'below-caption' && annotations.source)
+        ids.push(annotations.source);
+    if (target?.note_position !== 'above' && annotations.note)
+        ids.push(annotations.note);
+    if (target?.source_position !== 'above' && target?.source_position !== 'below-caption' && annotations.source) {
+        ids.push(annotations.source);
+    }
+    return ids;
+}
+function convertSemanticTable(ctx, wrapper, parentId) {
+    const semanticId = getStringProp(wrapper, 'semanticId') ?? undefined;
+    const table = getChildren(wrapper).find((child) => isElement(child) && child.tagName === 'table');
+    const annotations = semanticAnnotationIds(ctx, wrapper, parentId, semanticId);
+    const tableIds = table ? convertTable(ctx, table, parentId) : [];
+    for (const tableId of tableIds)
+        attachSemanticMeta(ctx, tableId, 'semantic-table', semanticId);
+    const target = ctx.semanticTarget.tables;
+    const ids = [];
+    if (target?.caption_position !== 'below' && annotations.caption)
+        ids.push(annotations.caption);
+    if (target?.source_position === 'above' && annotations.source)
+        ids.push(annotations.source);
+    ids.push(...tableIds);
+    if (target?.caption_position === 'below' && annotations.caption)
+        ids.push(annotations.caption);
+    if (annotations.note)
+        ids.push(annotations.note);
+    if (target?.source_position !== 'above' && annotations.source)
+        ids.push(annotations.source);
+    return ids;
+}
+function convertSemanticEquation(ctx, wrapper, parentId) {
+    const semanticId = getStringProp(wrapper, 'semanticId') ?? undefined;
+    const ids = [];
+    const equationNumber = getStringProp(wrapper, 'equationNumber');
+    let numberAttached = false;
+    for (const child of getChildren(wrapper)) {
+        if (isElement(child) && ['m2l-caption', 'm2l-note', 'm2l-source'].includes(child.tagName))
+            continue;
+        for (const blockId of convertBlock(ctx, child, parentId)) {
+            attachSemanticMeta(ctx, blockId, 'equation', semanticId);
+            const block = ctx.blocks[blockId];
+            if (equationNumber && !numberAttached && block && isTextualBlockNode(block)) {
+                block.payload.inlines.push({
+                    id: nextInlineId(ctx),
+                    kind: 'text_run',
+                    marks: createDefaultMarks(),
+                    text: ` (${equationNumber})`,
+                });
+                numberAttached = true;
+            }
+            ids.push(blockId);
+        }
+    }
+    const annotations = semanticAnnotationIds(ctx, wrapper, parentId, semanticId);
+    if (annotations.caption)
+        ids.push(annotations.caption);
+    if (annotations.note)
+        ids.push(annotations.note);
+    if (annotations.source)
+        ids.push(annotations.source);
+    return ids;
+}
+function prependFootnoteLabel(ctx, blockId, label) {
+    const block = ctx.blocks[blockId];
+    if (!block || !isTextualBlockNode(block))
+        return;
+    block.payload.inlines.unshift({
+        id: nextInlineId(ctx),
+        kind: 'text_run',
+        marks: { ...createDefaultMarks(), bold: true },
+        text: `[${label}] `,
+    });
+}
+function convertSemanticCallout(ctx, element, parentId, footnote) {
+    const output = [];
+    let calloutId = createCalloutBlock(ctx, parentId, element, footnote);
+    output.push(calloutId);
+    let firstText = true;
+    const appendConverted = (blockId) => {
+        const block = ctx.blocks[blockId];
+        if (!block)
+            return;
+        if (block.type === 'image' || block.type === 'table' || block.type === 'file' || block.type === 'board') {
+            block.parentId = parentId;
+            attachSemanticMeta(ctx, blockId, footnote ? 'footnote-media-sibling' : 'callout-media-sibling', getStringProp(element, 'semanticId') ?? undefined);
+            output.push(blockId);
+            calloutId = createCalloutBlock(ctx, parentId, element, footnote);
+            output.push(calloutId);
+            return;
+        }
+        const callout = ctx.blocks[calloutId];
+        if (!callout || callout.type !== 'callout')
+            return;
+        block.parentId = calloutId;
+        appendChild(callout, blockId);
+        if (footnote && firstText && isTextualBlockNode(block)) {
+            prependFootnoteLabel(ctx, blockId, getStringProp(element, 'semanticId') ?? '?');
+            firstText = false;
+        }
+    };
+    for (const child of getChildren(element)) {
+        const current = ctx.blocks[calloutId];
+        if (!current || current.type !== 'callout')
+            continue;
+        for (const blockId of convertBlock(ctx, child, calloutId))
+            appendConverted(blockId);
+    }
+    for (const blockId of [...output]) {
+        const block = ctx.blocks[blockId];
+        if (block?.type === 'callout' && block.children.length === 0) {
+            delete ctx.blocks[blockId];
+            output.splice(output.indexOf(blockId), 1);
+        }
+    }
+    return output;
+}
 function convertBlock(ctx, node, parentId) {
     if (isWhitespaceTextNode(node)) {
         return [];
@@ -842,8 +1191,25 @@ function convertBlock(ctx, node, parentId) {
             return [createDividerBlock(ctx, parentId)];
         case 'table':
             return convertTable(ctx, node, parentId);
+        case 'm2l-figure':
+            return convertSemanticFigure(ctx, node, parentId);
+        case 'm2l-table':
+            return convertSemanticTable(ctx, node, parentId);
+        case 'm2l-equation':
+            return convertSemanticEquation(ctx, node, parentId);
+        case 'm2l-callout':
+            return convertSemanticCallout(ctx, node, parentId, false);
+        case 'm2l-footnote':
+            return convertSemanticCallout(ctx, node, parentId, true);
+        case 'm2l-unknown-directive':
+        case 'm2l-caption':
+        case 'm2l-note':
+        case 'm2l-source':
+            return convertUnknownElement(ctx, node, parentId);
         case 'img':
-            return [createImageBlock(ctx, parentId, getStringProp(node, 'src'), getStringProp(node, 'alt'))];
+            return [
+                createImageBlock(ctx, parentId, getStringProp(node, 'src'), getStringProp(node, 'alt'), getStringProp(node, 'title')),
+            ];
         case 'br':
             return [
                 createTextualBlock(ctx, 'text', parentId, [
@@ -956,7 +1322,7 @@ function deepCloneBlock(value) {
     return JSON.parse(JSON.stringify(value));
 }
 export function hastToLAST(hast, options) {
-    const ctx = createContext();
+    const ctx = createContext(options);
     const mode = options?.mode ?? 'fragment';
     const rootId = createTextualBlock(ctx, 'page', null, []);
     const root = ctx.blocks[rootId];

package/dist/pipeline/index.js

@@ -1,3 +1,4 @@
 export { markdownToHast } from './markdown/md-to-hast.js';
+export { markdownToSemanticHast, parseDirectiveWidth } from './markdown/md-to-semantic-hast.js';
 export { prepareMarkdownBeforePublish } from './markdown/prepare-markdown.js';
 export { hastToLAST } from './hast-to-last.js';