@diplodoc/transform 4.74.1 → 4.75.1

package/src/scss/_table.scss

@@ -1,3 +1,4 @@
+.yfm table th,
 .yfm table td {
     &.cell-align-top-left,
     &.cell-align-bottom-left {
@@ -63,6 +64,18 @@
     }
 }
 
+.yfm table tr[data-header] {
+    & > th,
+    & > td {
+        &:not([class*='cell-bg-']) {
+            background: var(
+                --yfm-color-table-head-background,
+                var(--yfm-color-table-head-background-private)
+            );
+        }
+    }
+}
+
 .yfm table[sticky-header] {
     position: relative;
 

package/src/scss/_tooltip.scss

@@ -1,3 +1,15 @@
+.yfm-tooltip-live-region {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+}
+
 .yfm-tooltip {
     position: absolute;
     z-index: 100;

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

@@ -1,12 +1,14 @@
 import type StateBlock from 'markdown-it/lib/rules_block/state_block';
 import type Token from 'markdown-it/lib/token';
 import type {MarkdownItPluginCb} from '../typings';
-import type {YfmTablePluginOptions} from './types';
+import type {Logger} from '../../log';
+import type {TableAttrs, YfmTablePluginOptions} from './types';
 
-import {AttrsParser} from '@diplodoc/utils';
+import {AttrsParser, parseMdAttrs} from '@diplodoc/utils';
 
 const pluginName = 'yfm_table';
 const pipeChar = 0x7c; // |
+const colonChar = 0x3a; // :
 const apostropheChar = 0x60; // `
 const hashChar = 0x23; // #
 const backSlashChar = 0x5c; // \
@@ -225,10 +227,70 @@ class StateIterator {
     }
 }
 
+type CellData = {start: Stats; end: Stats; rawAttrs: TableAttrs};
+type RowData = {start: number; end: number; cols: CellData[]; rawAttrs: TableAttrs};
+
 interface RowPositions {
-    rows: [number, number, [Stats, Stats][]][];
+    rows: RowData[];
     endOfTable: number | null;
     pos: number;
+    tableAttrs: TableAttrs;
+}
+
+/**
+ * Parses table options from lines between #| and the first || or |#.
+ *
+ * Option line format: `|:{key="value" key2="value2"}`
+ * Multiple option lines are supported; results are merged.
+ */
+function parseTableAttrs(state: StateBlock, iter: StateIterator): TableAttrs {
+    const options: TableAttrs = {};
+    const {src} = state;
+    const utils = state.md.utils;
+
+    let parsing = true;
+
+    while (parsing) {
+        const lineEnd = iter.lineEnds;
+
+        // Skip leading whitespace to find first non-space char
+        let first = iter.pos;
+        while (first < lineEnd && utils.isSpace(src.charCodeAt(first))) {
+            first++;
+        }
+
+        // Skip empty lines
+        if (first >= lineEnd) {
+            iter.next(lineEnd - iter.pos + 1);
+            continue;
+        }
+
+        // Stop if we hit row start || or table close |#
+        if (isRowOrder(src, first) || isCloseTableOrder(src, first)) {
+            parsing = false;
+            continue;
+        }
+
+        // Option line must start with |:
+        if (src.charCodeAt(first) !== pipeChar || src.charCodeAt(first + 1) !== colonChar) {
+            parsing = false;
+            continue;
+        }
+
+        const result = parseMdAttrs(state.md, src, first + 2, lineEnd);
+        if (!result) {
+            parsing = false;
+            continue;
+        }
+
+        for (const [key, values] of Object.entries(result.attrs)) {
+            options[key] = values[values.length - 1];
+        }
+
+        iter.next(lineEnd - iter.pos + 1);
+    }
+
+    return options;
 }
 
 // eslint-disable-next-line complexity
@@ -241,13 +303,17 @@ function getTableRowPositions(
 ): RowPositions {
     let endOfTable = null;
     let tableLevel = 0;
-    let currentRow: [Stats, Stats][] = [];
+    let currentRow: CellData[] = [];
     let colStart: Stats | null = null;
+    let pendingCellAttrs: TableAttrs = {};
     let rowStart: number | null = null;
+    let currentRowAttrs: TableAttrs = {};
 
     const iter = new StateIterator(state, startPosition + openTableOrder.length, startLine);
 
-    const rows: [number, number, typeof currentRow][] = [];
+    const tableAttrs = parseTableAttrs(state, iter);
+
+    const rows: RowData[] = [];
 
     let isInsideCode = false;
     let isInsideMath = false;
@@ -256,14 +322,21 @@ function getTableRowPositions(
 
     const addRow = () => {
         if (colStart) {
-            currentRow.push([colStart, iter.stats()]);
+            currentRow.push({start: colStart, end: iter.stats(), rawAttrs: pendingCellAttrs});
+            pendingCellAttrs = {};
         }
         if (currentRow.length && rowStart) {
-            rows.push([rowStart, iter.line, currentRow]);
+            rows.push({
+                start: rowStart,
+                end: iter.line,
+                cols: currentRow,
+                rawAttrs: currentRowAttrs,
+            });
         }
         currentRow = [];
         colStart = null;
         rowStart = null;
+        currentRowAttrs = {};
     };
 
     while (iter.pos <= endPosition) {
@@ -356,6 +429,36 @@ function getTableRowPositions(
             } else {
                 iter.next(rowStartOrder.length);
                 rowStart = iter.line;
+
+                const hasRowAttrs =
+                    iter.pos <= iter.lineEnds &&
+                    state.src.charCodeAt(iter.pos) === colonChar &&
+                    state.src.charCodeAt(iter.pos + 1) === curlyBraceOpen;
+                if (hasRowAttrs) {
+                    currentRowAttrs = parseInlineAttrs(state, iter, 1);
+                } else {
+                    currentRowAttrs = {};
+                }
+
+                // skip spaces/tabs on same line only if row attrs were present, then check for first-cell attrs ::{...}
+                if (hasRowAttrs) {
+                    while (
+                        iter.pos <= iter.lineEnds &&
+                        state.md.utils.isSpace(state.src.charCodeAt(iter.pos))
+                    ) {
+                        iter.next(1);
+                    }
+                }
+                if (
+                    iter.pos <= iter.lineEnds &&
+                    state.src.charCodeAt(iter.pos) === colonChar &&
+                    state.src.charCodeAt(iter.pos + 1) === colonChar
+                ) {
+                    pendingCellAttrs = parseInlineAttrs(state, iter, 2);
+                } else {
+                    pendingCellAttrs = {};
+                }
+
                 colStart = iter.stats();
             }
 
@@ -366,9 +469,20 @@ function getTableRowPositions(
 
         if (isCellOrder(state.src, iter.pos)) {
             if (colStart) {
-                currentRow.push([colStart, iter.stats()]);
+                currentRow.push({start: colStart, end: iter.stats(), rawAttrs: pendingCellAttrs});
+                pendingCellAttrs = {};
             }
             iter.next(cellStartOrder.length);
+            // check for cell attrs ::{...} immediately after | (no spaces allowed)
+            if (
+                iter.pos <= iter.lineEnds &&
+                state.src.charCodeAt(iter.pos) === colonChar &&
+                state.src.charCodeAt(iter.pos + 1) === colonChar
+            ) {
+                pendingCellAttrs = parseInlineAttrs(state, iter, 2);
+            } else {
+                pendingCellAttrs = {};
+            }
             colStart = iter.stats();
             continue;
         }
@@ -378,7 +492,20 @@ function getTableRowPositions(
 
     const {pos} = iter;
 
-    return {rows, endOfTable, pos};
+    return {rows, endOfTable, pos, tableAttrs};
+}
+
+function parseInlineAttrs(state: StateBlock, iter: StateIterator, prefixLen: number): TableAttrs {
+    const result: TableAttrs = {};
+    const parsed = parseMdAttrs(state.md, state.src, iter.pos + prefixLen, iter.lineEnds);
+    if (!parsed) {
+        return result;
+    }
+    for (const [key, values] of Object.entries(parsed.attrs)) {
+        result[key] = values[0];
+    }
+    iter.next(parsed.pos - iter.pos);
+    return result;
 }
 
 function extractAttributes(state: StateBlock, pos: number): Record<string, string[]> {
@@ -396,9 +523,10 @@ function extractAttributes(state: StateBlock, pos: number): Record<string, strin
  *
  * @param {Token} contentToken - Search the content of this token for the class.
  * @param {Token} tdOpenToken - Parent td_open token. Extracted class is applied to this token.
+ * @param {Logger} log - Logger instance for deprecation warnings.
  * @returns {void}
  */
-function extractAndApplyClassFromToken(contentToken: Token, tdOpenToken: Token): void {
+function extractAndApplyClassFromToken(contentToken: Token, tdOpenToken: Token, log: Logger): void {
     // Regex to find class attribute in any position within brackets
     const blockRegex = /\s*\{[^}]*}$/;
     const allAttrs = contentToken.content.match(blockRegex);
@@ -410,7 +538,12 @@ function extractAndApplyClassFromToken(contentToken: Token, tdOpenToken: Token):
     const attrsClass = attrs?.class?.join(' ');
 
     if (attrsClass) {
-        tdOpenToken.attrSet('class', attrsClass);
+        if (attrsClass.split(' ').some((c) => c.startsWith('cell-align-'))) {
+            log.warn(
+                `Deprecated: use align="..." inside cell attributes "::{align=\\"...\\"}" instead of .cell-align-* class in cell content "{ }"`,
+            );
+        }
+        tdOpenToken.attrJoin('class', attrsClass);
         // remove the class from the token so that it's not propagated to tr or table level
         let replacedContent = allAttrs[0].replace(`.${attrsClass}`, '');
         if (replacedContent.trim() === '{}') {
@@ -420,6 +553,52 @@ function extractAndApplyClassFromToken(contentToken: Token, tdOpenToken: Token):
     }
 }
 
+const VALID_ALIGN_VALUES: ReadonlySet<string> = new Set([
+    'top-left',
+    'top-center',
+    'top-right',
+    'center',
+    'bottom-left',
+    'bottom-right',
+]);
+
+function parseHeaderRows(rawAttrs: TableAttrs, log: Logger): number | null {
+    if (!('header-rows' in rawAttrs)) return null;
+    const raw = rawAttrs['header-rows'];
+    const trimmed = raw.trim();
+    const parsed = Number.parseInt(trimmed, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0 || String(parsed) !== trimmed) {
+        log.warn(`Invalid table header-rows value: "${raw}"`);
+        return null;
+    }
+    return parsed;
+}
+
+function applyCellAttrs(token: Token, rawAttrs: TableAttrs, log: Logger): void {
+    if ('align' in rawAttrs) {
+        const value = rawAttrs['align'];
+        if (!VALID_ALIGN_VALUES.has(value)) {
+            log.warn(`Unknown table cell align value: "${value}"`);
+        }
+        token.meta = token.meta || {};
+        token.meta.align = value;
+        token.attrSet('data-align', value);
+        if (value) {
+            token.attrJoin('class', `cell-align-${value}`);
+        }
+    }
+
+    if ('bg' in rawAttrs) {
+        const value = rawAttrs['bg'];
+        token.meta = token.meta || {};
+        token.meta.bg = value;
+        token.attrSet('data-bg', value);
+        if (value) {
+            token.attrJoin('class', `cell-bg-${value}`);
+        }
+    }
+}
+
 const COLSPAN_SYMBOL = '>';
 const ROWSPAN_SYMBOL = '^';
 
@@ -539,7 +718,7 @@ const yfmTable: MarkdownItPluginCb<YfmTablePluginOptions> = (md, opts) => {
                 return true;
             }
 
-            const {rows, endOfTable, pos} = getTableRowPositions(
+            const {rows, endOfTable, pos, tableAttrs} = getTableRowPositions(
                 state,
                 startPosition,
                 endPosition,
@@ -575,11 +754,19 @@ const yfmTable: MarkdownItPluginCb<YfmTablePluginOptions> = (md, opts) => {
             }
 
             token.map = [startLine, endOfTable];
+            token.meta = token.meta || {};
+            token.meta.rawAttrs = tableAttrs;
+
+            const headerRows = parseHeaderRows(tableAttrs, opts.log);
+            if (headerRows !== null) {
+                token.meta.headerRows = headerRows;
+                token.attrSet('data-header-rows', String(headerRows));
+            }
 
             token = state.push('yfm_tbody_open', 'tbody', 1);
             token.map = [startLine + 1, endOfTable - 1];
 
-            const maxRowLength = Math.max(...rows.map(([, , cols]) => cols.length));
+            const maxRowLength = Math.max(...rows.map((row) => row.cols.length));
 
             // cellsMaps is a 2-D map of all td_open tokens in the table.
             // cellsMap is used to access the table cells by [row][column] coordinates
@@ -590,19 +777,38 @@ const yfmTable: MarkdownItPluginCb<YfmTablePluginOptions> = (md, opts) => {
             const contentMap: string[][] = [];
 
             for (let i = 0; i < rows.length; i++) {
-                const [rowLineStarts, rowLineEnds, cols] = rows[i];
+                const {
+                    start: rowLineStarts,
+                    end: rowLineEnds,
+                    cols,
+                    rawAttrs: rowRawAttrs,
+                } = rows[i];
                 cellsMap.push([]);
                 contentMap.push([]);
                 const rowLength = cols.length;
 
+                const isHeaderRow = headerRows !== null && i < headerRows;
+                const cellTag = isHeaderRow ? 'th' : 'td';
+
                 token = state.push('yfm_tr_open', 'tr', 1);
                 token.map = [rowLineStarts, rowLineEnds];
+                token.meta = token.meta || {};
+                token.meta.rawAttrs = rowRawAttrs;
+                if (isHeaderRow) {
+                    token.attrSet('data-header', 'true');
+                }
 
                 for (let j = 0; j < cols.length; j++) {
-                    const [begin, end] = cols[j];
-                    token = state.push('yfm_td_open', 'td', 1);
+                    const {start: begin, end, rawAttrs: cellRawAttrs} = cols[j];
+                    token = state.push('yfm_td_open', cellTag, 1);
                     cellsMap[i].push(token);
                     token.map = [begin.line, end.line];
+                    token.meta = token.meta || {};
+                    token.meta.rawAttrs = cellRawAttrs;
+                    if (isHeaderRow) {
+                        token.attrSet('scope', 'col');
+                    }
+                    applyCellAttrs(token, cellRawAttrs, opts.log);
 
                     const oldTshift = state.tShift[begin.line];
                     const oldEMark = state.eMarks[end.line];
@@ -622,7 +828,7 @@ const yfmTable: MarkdownItPluginCb<YfmTablePluginOptions> = (md, opts) => {
                     const content = contentToken.content.trim() || contentToken.markup.trim();
                     contentMap[i].push(content);
 
-                    token = state.push('yfm_td_close', 'td', -1);
+                    token = state.push('yfm_td_close', cellTag, -1);
                     state.tokens[state.tokens.length - 1].map = [end.line, end.line + 1];
 
                     state.lineMax = oldLineMax;
@@ -631,14 +837,21 @@ const yfmTable: MarkdownItPluginCb<YfmTablePluginOptions> = (md, opts) => {
                     state.eMarks[end.line] = oldEMark;
 
                     const rowTokens = cellsMap[cellsMap.length - 1];
-                    extractAndApplyClassFromToken(contentToken, rowTokens[rowTokens.length - 1]);
+                    extractAndApplyClassFromToken(
+                        contentToken,
+                        rowTokens[rowTokens.length - 1],
+                        opts.log,
+                    );
                 }
 
                 if (rowLength < maxRowLength) {
                     const emptyCellsCount = maxRowLength - rowLength;
                     for (let k = 0; k < emptyCellsCount; k++) {
-                        token = state.push('yfm_td_open', 'td', 1);
-                        token = state.push('yfm_td_close', 'td', -1);
+                        token = state.push('yfm_td_open', cellTag, 1);
+                        if (isHeaderRow) {
+                            token.attrSet('scope', 'col');
+                        }
+                        token = state.push('yfm_td_close', cellTag, -1);
                     }
                 }
 

package/src/transform/plugins/table/types.ts

@@ -1,3 +1,5 @@
+export type TableAttrs = Record<string, string>;
+
 export type YfmTablePluginOptions = {
     /**
      * Sets whether to interpret the pipe symbol inside the code block as a table separator.

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

@@ -251,6 +251,15 @@ function removeUnreferencedDefinitions(tokens: Token[], referencedTerms: Set<str
     }
 }
 
+/**
+ * Eagerly initialize env.terms before the includes core rule runs
+ */
+function termInit(state: StateCore) {
+    if (!state.env.terms) {
+        state.env.terms = {};
+    }
+}
+
 const term: MarkdownItPluginCb = (md, options) => {
     const escapeRE = md.utils.escapeRE;
     const arrayReplaceAt = md.utils.arrayReplaceAt;
@@ -391,9 +400,12 @@ const term: MarkdownItPluginCb = (md, options) => {
             }
         }
 
-        // Remove definitions without any reference on the page
-        // Skip during linting to allow lint rules to check term definitions
-        if (!isLintRun) {
+        // Remove definitions without any reference on the page.
+        // Skip during linting to allow lint rules to check term definitions.
+        // Skip when inside an include sub-parse (env.includes is non-empty)
+        const insideInclude = Array.isArray(state.env.includes) && state.env.includes.length > 0;
+
+        if (!isLintRun && !insideInclude) {
             removeUnreferencedDefinitions(state.tokens, referencedTerms);
         }
     }
@@ -402,6 +414,10 @@ const term: MarkdownItPluginCb = (md, options) => {
         alt: ['paragraph', 'reference'],
     });
 
+    try {
+        md.core.ruler.before('includes', 'termInit', termInit);
+    } catch {}
+
     // Register termReplace after text_join so that emphasis-split text
     // tokens (e.g. [text](*key) where * opens a delimiter) are merged
     // before the term regex runs.  Without this, terms defined in