@diplodoc/transform 4.70.4 → 4.72.0

package/src/js/tooltip/types.ts

@@ -0,0 +1,59 @@
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+export interface ElementRect {
+    readonly top: number;
+    readonly left: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly width: number;
+    readonly height: number;
+}
+
+export interface Coords {
+    x: number;
+    y: number;
+}
+
+export interface OffsetValues {
+    mainAxis?: number;
+    crossAxis?: number;
+}
+
+export type Alignment = 'start' | 'end';
+
+export type Side = 'top' | 'right' | 'bottom' | 'left';
+
+export type AlignedPlacement = `${Side}-${Alignment}`;
+
+export type Placement = Prettify<Side | AlignedPlacement>;
+
+export type SideObject = {[key in Side]: number};
+
+export interface TooltipContextElements {
+    reference: HTMLElement;
+    tooltip: HTMLElement;
+    offsetParent: HTMLElement;
+}
+
+export interface TooltipContext {
+    isRtl: boolean;
+    viewport: ElementRect;
+    reference: ElementRect;
+    tooltip: ElementRect;
+    elements: TooltipContextElements;
+}
+
+export interface TooltipElementOptions {
+    text: string;
+    className?: string;
+}
+
+export interface TooltipOptions {
+    closeDelay?: number;
+    additionalClassName?: string;
+    placement?: Placement;
+    offset?: OffsetValues;
+    flip?: boolean;
+}

package/src/js/tooltip/utils.ts

@@ -0,0 +1,247 @@
+import type {
+    Alignment,
+    Coords,
+    ElementRect,
+    OffsetValues,
+    Placement,
+    Side,
+    SideObject,
+} from './types';
+
+import {DEFAULT_SIDE_OBJECT, OPPOSITE_SIDES} from './constant';
+
+function isVerticalSide(side: Side): boolean {
+    return side === 'top' || side === 'bottom';
+}
+
+function createSideObject(value: Partial<SideObject> | number = 0): SideObject {
+    if (typeof value === 'number') {
+        return {top: value, bottom: value, left: value, right: value};
+    }
+
+    return {...DEFAULT_SIDE_OBJECT, ...value};
+}
+
+function parsePlacement(placement: Placement): {side: Side; alignment?: Alignment} {
+    const [side, alignment] = placement.split('-') as [Side, Alignment | undefined];
+
+    return {side, alignment};
+}
+
+function getOppositeSide(side: Side): Side {
+    return OPPOSITE_SIDES[side];
+}
+
+function flipPlacement(placement: Placement): Placement {
+    const {side, alignment} = parsePlacement(placement);
+    const opposite = getOppositeSide(side);
+
+    return (alignment ? `${opposite}-${alignment}` : opposite) as Placement;
+}
+
+function getOverflow(tooltip: ElementRect, coords: Coords, viewport: ElementRect): SideObject {
+    const rect = updateRect(tooltip, {top: coords.y, left: coords.x});
+
+    return detectOverflow(viewport, rect, 5);
+}
+
+function shouldFlip(overflow: SideObject, flippedOverflow: SideObject, side: Side): boolean {
+    const opposite = getOppositeSide(side);
+
+    return overflow[side] > 0 && flippedOverflow[opposite] < overflow[side];
+}
+
+export function computePosition(
+    reference: ElementRect,
+    tooltip: ElementRect,
+    viewport: ElementRect,
+    placement: Placement,
+    offset: OffsetValues,
+    isRtl: boolean,
+    flip = true,
+): {coords: Coords; placement: Placement} {
+    const coords = computeCoordsFromPlacement(reference, tooltip, offset, placement, isRtl);
+
+    if (!flip) {
+        return {coords, placement};
+    }
+
+    const overflow = getOverflow(tooltip, coords, viewport);
+    const {side} = parsePlacement(placement);
+
+    if (overflow[side] <= 0) {
+        return {coords, placement};
+    }
+
+    const flipped = flipPlacement(placement);
+    const flippedCoords = computeCoordsFromPlacement(reference, tooltip, offset, flipped, isRtl);
+    const flippedOverflow = getOverflow(tooltip, flippedCoords, viewport);
+
+    if (shouldFlip(overflow, flippedOverflow, side)) {
+        return {coords: flippedCoords, placement: flipped};
+    }
+
+    return {coords, placement};
+}
+
+export function generateId() {
+    const random = Math.random().toString(36).substring(2, 6);
+    const now = Date.now().toString(36);
+
+    return `${random}${now}`;
+}
+
+export function createRect(
+    params: Pick<ElementRect, 'top' | 'left' | 'width' | 'height'>,
+): ElementRect {
+    return {
+        ...params,
+        right: params.left + params.width,
+        bottom: params.top + params.height,
+    };
+}
+
+export function updateRect(rect: ElementRect, params: Partial<ElementRect>): ElementRect {
+    return createRect({
+        top: params.top ?? rect.top,
+        left: params.left ?? rect.left,
+        width: params.width ?? rect.width,
+        height: params.height ?? rect.height,
+    });
+}
+
+export function getViewportRect(): ElementRect {
+    const {documentElement, body} = document;
+
+    const scrollTop = window.scrollY || documentElement.scrollTop || body.scrollTop;
+    const scrollLeft = window.scrollX || documentElement.scrollLeft || body.scrollLeft;
+
+    const clientTop = documentElement.clientTop || body.clientTop || 0;
+    const clientLeft = documentElement.clientLeft || body.clientLeft || 0;
+
+    return createRect({
+        top: Math.round(scrollTop - clientTop),
+        left: Math.round(scrollLeft - clientLeft),
+        width: document.body.clientWidth,
+        height: document.body.clientHeight,
+    });
+}
+
+export function getElementRect(element: HTMLElement): ElementRect {
+    const viewport = getViewportRect();
+    const box = element.getBoundingClientRect();
+
+    return createRect({
+        top: Math.round(box.top + viewport.top),
+        left: Math.round(box.left + viewport.left),
+        width: box.width,
+        height: box.height,
+    });
+}
+
+export function computeAxisOffset(offset: OffsetValues, side: Side, isRtl?: boolean): Coords {
+    const {mainAxis = 0, crossAxis = 0} = offset;
+
+    const isVertical = isVerticalSide(side);
+    const mainDirection = side === 'top' || side === 'left' ? -1 : 1;
+    const crossDirection = isRtl && isVertical ? -1 : 1;
+
+    const mainOffset = mainAxis * mainDirection;
+    const crossOffset = crossAxis * crossDirection;
+
+    if (isVertical) {
+        return {x: crossOffset, y: mainOffset};
+    }
+
+    return {x: mainOffset, y: crossOffset};
+}
+
+export function computeCoordsFromPlacement(
+    reference: ElementRect,
+    tooltip: ElementRect,
+    offset: OffsetValues,
+    placement: Placement,
+    isRtl: boolean,
+) {
+    const {side, alignment} = parsePlacement(placement);
+    const isVertical = isVerticalSide(side);
+    const alignmentAxis = isVertical ? 'x' : 'y';
+    const alignLength = alignmentAxis === 'y' ? 'height' : 'width';
+
+    const centerX = reference.left + reference.width / 2 - tooltip.width / 2;
+    const centerY = reference.top + reference.height / 2 - tooltip.height / 2;
+    const alignmentOffset = reference[alignLength] / 2 - tooltip[alignLength] / 2;
+
+    const coords: Coords = {x: reference.left, y: reference.top};
+
+    switch (side) {
+        case 'top': {
+            coords.x = centerX;
+            coords.y = reference.top - tooltip.height;
+            break;
+        }
+
+        case 'bottom': {
+            coords.x = centerX;
+            coords.y = reference.top + reference.height;
+            break;
+        }
+
+        case 'right': {
+            coords.x = reference.left + reference.width;
+            coords.y = centerY;
+            break;
+        }
+
+        case 'left': {
+            coords.x = reference.left - tooltip.width;
+            coords.y = centerY;
+            break;
+        }
+    }
+
+    switch (alignment) {
+        case 'start': {
+            coords[alignmentAxis] -= alignmentOffset * (isRtl && isVertical ? -1 : 1);
+            break;
+        }
+
+        case 'end': {
+            coords[alignmentAxis] += alignmentOffset * (isRtl && isVertical ? -1 : 1);
+            break;
+        }
+    }
+
+    const axisOffset = computeAxisOffset(offset, side, isRtl);
+
+    coords.x += axisOffset.x;
+    coords.y += axisOffset.y;
+
+    return coords;
+}
+
+export function convertToRelativeToOffsetParentRect(rect: ElementRect, offsetParent: HTMLElement) {
+    const offsetRect = getElementRect(offsetParent);
+
+    return createRect({
+        top: rect.top - offsetRect.top + offsetParent.offsetTop,
+        left: rect.left - offsetRect.left + offsetParent.offsetLeft,
+        width: rect.width,
+        height: rect.height,
+    });
+}
+
+export function detectOverflow(
+    boundary: ElementRect,
+    element: ElementRect,
+    padding: Partial<SideObject> | number = 0,
+): SideObject {
+    const {top, bottom, left, right} = createSideObject(padding);
+
+    return {
+        top: boundary.top - element.top + top,
+        bottom: element.bottom - boundary.bottom + bottom,
+        left: boundary.left - element.left + left,
+        right: element.right - boundary.right + right,
+    };
+}

package/src/scss/{_inline-code.scss → _tooltip.scss}

@@ -1,4 +1,4 @@
-.inline_code_tooltip {
+.yfm-tooltip {
     position: absolute;
     z-index: 100;
 

package/src/scss/_yfm-only.scss

@@ -10,4 +10,4 @@
 @use 'katex';
 @use 'table';
 @use 'term';
-@use 'inline-code';
+@use 'tooltip';

package/src/transform/plugins/anchors/index.ts

@@ -46,7 +46,7 @@ function createAnchorLinkTokens(
         open.attrSet('id', id);
     }
     open.attrSet('href', href + '#' + id);
-    open.attrSet('class', 'yfm-anchor');
+    open.attrSet('class', 'yfm-anchor yfm-clipboard-anchor');
     open.attrSet('aria-hidden', 'true');
 
     // SEO: render invisible heading title because link must have text content.

package/src/transform/plugins/images/index.ts

@@ -147,6 +147,7 @@ const index: MarkdownItPluginCb<Opts> = (md, opts) => {
                 const imageOpts = {
                     width: image.attrGet('width'),
                     height: image.attrGet('height'),
+                    title: image.attrGet('title'),
                 };
 
                 const from = state.env.path || opts.path;
@@ -225,6 +226,13 @@ function replaceSvgContent(content: string | null, options: ImageOptions) {
         content = content.replace(/.*?<svg([^>]*)>/, `<svg${svgRoot}>`);
     }
 
+    // title
+    const hasTitle = /<title>.*?<\/title>/i.test(content);
+    if (!hasTitle && options.title) {
+        // Insert title tag after the opening svg tag
+        content = content.replace(/(<svg[^>]*>)/, `$1<title>${options.title}</title>`);
+    }
+
     // randomize ids
     content = optimize(content, {
         plugins: [

package/src/transform/plugins/term/termDefinitions.ts

@@ -6,24 +6,38 @@ import {BASIC_TERM_REGEXP} from './constants';
 
 const INCLUDE_LINE_RE = /^{%\s*include\s/;
 const NEW_LINE_RE = /^(\r\n|\r|\n)/;
-const TERM_DEF_RE = /^\[\*(\w+)\]:/;
+const TERM_DEF_RE = /^\[\*([^[\]]+)\]:/;
+
+/**
+ * @param state - markdown-it block state
+ * @param line - line number to read
+ * @returns raw source text of the given line
+ */
+function getNextLineContent(state: StateBlock, line: number): string {
+    const start = state.bMarks[line];
+    const end = state.eMarks[line];
+
+    return start === end ? state.src[start] : state.src.slice(start, end);
+}
 
 /**
  * Checks whether the first non-blank line after {@link fromLine} is an
  * `{% include %}` directive.  Used to allow blank-line gaps between
  * consecutive includes inside a single term definition.
  *
- * @param {StateBlock} state - The markdown-it state block containing parsing information
- * @param {number} fromLine - The line number from which to start searching for include directives
- * @param {number} endLine - The last line number to search within
- * @returns {boolean} Returns true if an include directive is found after blank lines, false otherwise
+ * @param state - markdown-it block state
+ * @param fromLine - line number from which to start searching
+ * @param endLine - last line number to search within
+ * @returns true if the first non-blank line is an include directive
  */
 function hasIncludeAfterBlanks(state: StateBlock, fromLine: number, endLine: number): boolean {
     for (let line = fromLine + 1; line <= endLine; line++) {
         const start = state.bMarks[line];
         const end = state.eMarks[line];
 
-        if (start === end) continue;
+        if (start === end) {
+            continue;
+        }
 
         const content = state.src.slice(start, end);
         return INCLUDE_LINE_RE.test(content.trimStart());
@@ -31,7 +45,51 @@ function hasIncludeAfterBlanks(state: StateBlock, fromLine: number, endLine: num
     return false;
 }
 
+/**
+ * Scans forward from {@link startLine} to find where the current term
+ * definition ends.
+ *
+ * When `multilineTermDefinitions` is enabled, the definition continues
+ * past blank lines and stops only at the next `[*key]:` or end of block.
+ * Otherwise blank lines terminate the definition unless followed by an
+ * `{% include %}` directive (legacy behaviour).
+ *
+ * @param state - markdown-it block state
+ * @param startLine - line where the current definition starts
+ * @param endLine - last line of the block
+ * @param multiline - whether multiline mode is enabled
+ * @returns line number where the definition ends
+ */
+function findDefinitionEnd(
+    state: StateBlock,
+    startLine: number,
+    endLine: number,
+    multiline: boolean,
+): number {
+    let currentLine = startLine;
+
+    for (; currentLine < endLine; currentLine++) {
+        const nextLine = getNextLineContent(state, currentLine + 1);
+
+        if (TERM_DEF_RE.test(nextLine)) {
+            break;
+        }
+
+        if (!multiline && NEW_LINE_RE.test(nextLine)) {
+            if (!hasIncludeAfterBlanks(state, currentLine + 1, endLine)) {
+                break;
+            }
+        }
+
+        state.line = currentLine + 1;
+    }
+
+    return currentLine;
+}
+
 export function termDefinitions(md: MarkdownIt, options: MarkdownItPluginOpts) {
+    const multiline = options.multilineTermDefinitions === true;
+
     return (state: StateBlock, startLine: number, endLine: number, silent: boolean) => {
         let ch;
         let labelEnd;
@@ -63,33 +121,7 @@ export function termDefinitions(md: MarkdownIt, options: MarkdownItPluginOpts) {
             }
         }
 
-        let currentLine = startLine;
-
-        // Allow multiline term definition.
-        // Blank lines normally terminate the definition, but we look ahead
-        // past them: if the next non-blank line is an {% include %} directive,
-        // we keep scanning so that multiple includes can be part of one term.
-        for (; currentLine < endLine; currentLine++) {
-            const nextLineStart = state.bMarks[currentLine + 1];
-            const nextLineEnd = state.eMarks[currentLine + 1];
-
-            const nextLine =
-                nextLineStart === nextLineEnd
-                    ? state.src[nextLineStart]
-                    : state.src.slice(nextLineStart, nextLineEnd);
-
-            if (TERM_DEF_RE.test(nextLine)) {
-                break;
-            }
-
-            if (NEW_LINE_RE.test(nextLine)) {
-                if (!hasIncludeAfterBlanks(state, currentLine + 1, endLine)) {
-                    break;
-                }
-            }
-
-            state.line = currentLine + 1;
-        }
+        const currentLine = findDefinitionEnd(state, startLine, endLine, multiline);
 
         max = state.eMarks[currentLine];
 
@@ -165,6 +197,8 @@ function processTermDefinition(
         state.env.terms[':' + label] = title;
     }
 
+    const fromInclude = Array.isArray(state.env.includes) && state.env.includes.length > 0;
+
     token = new state.Token('dfn_open', 'dfn', 1);
     token.attrSet('class', 'yfm yfm-term_dfn');
     token.attrSet('id', ':' + label + '_element');
@@ -172,6 +206,10 @@ function processTermDefinition(
     token.attrSet('aria-live', 'polite');
     token.attrSet('aria-modal', 'true');
 
+    if (fromInclude) {
+        token.attrSet('from-include', 'true');
+    }
+
     state.tokens.push(token);
 
     const titleTokens = md.parse(title, state.env);

package/src/transform/typings.ts

@@ -144,6 +144,15 @@ export interface MarkdownItPluginOpts {
         enabled: boolean;
         maxFileSize: number;
     };
+    /**
+     * When true, term definitions continue past blank lines until the next
+     * `[*key]:` or end of block. Designed for documents where all term
+     * definitions are placed at the end of the file.
+     *
+     * When false (default), a blank line terminates the definition unless
+     * the next non-blank line is an `{% include %}` directive.
+     */
+    multilineTermDefinitions?: boolean;
 }
 
 export type MarkdownItPluginCb<T extends {} = {}> = {
@@ -174,4 +183,5 @@ export type CssWhiteList = {[property: string]: boolean};
 export type ImageOptions = {
     width: string | undefined | null;
     height: string | undefined | null;
+    title: string | undefined | null;
 };