@adobe/helix-markdown-support 3.1.8 → 4.0.2

package/src/gridtable/index.js

@@ -0,0 +1,91 @@
+/*
+ * Copyright 2022 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * GridTables remark plugin and micromark extension.
+ *
+ * GridTables look like this:
+ *
+ * ```
+ * +-------------------+------+
+ * | Table Headings    | Here |
+ * +--------+----------+------+
+ * | Sub    | Headings | Too  |
+ * +========+=================+
+ * | cell   | column spanning |
+ * | spans  +---------:+------+
+ * | rows   |   normal | cell |
+ * +---v----+:---------------:+
+ * |        | cells can be    |
+ * |        | *formatted*     |
+ * |        | **paragraphs**  |
+ * |        | ```             |
+ * | multi  | and contain     |
+ * | line   | blocks          |
+ * | cells  | ```             |
+ * +========+=========<+======+
+ * | footer |    cells |      |
+ * +--------+----------+------+
+ * ```
+ *
+ * - the top of a cell must be indicated by `+-` followed by some `-` or `+` and finished by `-+`.
+ * - if the table contains a footer but no header, the top row should use `=` as grid line.
+ * - col spans are indicated by missing column (`|`) delimiters
+ * - row spans are indicated by missing row (`-`) delimiters
+ * - cells can be left, center, right, or justify aligned; indicated by the placement of `:` or `><`
+ * - cells can be top, middle, or bottom v-aligned;
+ *   indicated by the placement of arrows (`v` `^` `x`)
+ * - the header and footer sections are delimited by section delimiters (`=`).
+ * - if no section delimiters are present, all cells are placed in the table body.
+ * - if only 1 section delimiter is present, it delimits header from body.
+ * - the content in cells can be a full Markdown document again.
+ *   note, that the cell boundaries (`|`)
+ *   need to exactly match with the column markers (`+`) in the row delimiters, if the cell content
+ *   contains `|`, otherwise the correct layout of the table can't be guaranteed.
+ *
+ * Layout
+ * ======
+ *
+ * The table layout tries to keep the table within a certain width (default 120). For example,
+ * if the table has 3 columns, each column will be max 40 characters wide. If all text in a column
+ * is smaller, it will shrink the columns. However, cells have a minimum width (default 10) when
+ * text needs to be broken. If the cell contents need more space, e.g. with a nested table or
+ * code block, it will grow accordingly.
+ *
+ * Align
+ * =====
+ *
+ * Horizontal align is indicated by placing markers at the grid line above the cell:
+ *
+ * ```
+ * Justify     Center     Left       Right
+ * +>-----<+  +:-----:+  +:------+  +------:+
+ * | A b C |  |  ABC  |  | ABC   |  |   ABC |
+ * +-------+  +-------+  +-------+  +-------+
+ * ```
+ *
+ * Vertical align is indicated by placing markers at the center of the grid line above the cell:
+ *
+ * ```
+ * Top        Middle     Bottom
+ * +---^---+  +---x---+  +---v---+
+ * | Larum |  |       |  |       |
+ * | Ipsum |  | Larum |  |       |
+ * |       |  | Ipsum |  | Larum |
+ * |       |  |       |  | Ipsum |
+ * +-------+  +-------+  +-------+
+ * ```
+ *
+ */
+export * from './types.js';
+export { default as remarkGridTable } from './remark-plugin.js';
+export { default as mdast2hastGridTableHandler } from './mdast2hast-handler.js';

package/src/gridtable/mdast2hast-handler.js

@@ -0,0 +1,119 @@
+/*
+ * Copyright 2022 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { all } from 'mdast-util-to-hast';
+import { CONTINUE, SKIP, visit } from 'unist-util-visit';
+import {
+  TYPE_BODY, TYPE_CELL, TYPE_FOOTER, TYPE_HEADER, TYPE_ROW,
+} from './types.js';
+
+/**
+ * @typedef GridTableHandlerOptions
+ * @property {boolean} noHeader if true, <thead> and <tbody> elements are suppressed.
+ */
+
+/**
+ * Handles a row (i.e. the `gtRow` node)
+ * @return {HastNode} the 'tr' node
+ */
+function handleRow(h, node, cellElementName) {
+  const cells = [];
+  for (const child of node.children) {
+    if (child.type === TYPE_CELL) {
+      const props = {};
+      for (const p of ['colSpan', 'rowSpan', 'align', 'valign']) {
+        if (p in child) {
+          props[p] = child[p];
+        }
+      }
+      // if cell contains only 1 single paragraph, unwrap it
+      if (child.children?.length === 1 && child.children[0].type === 'paragraph') {
+        child.children = child.children[0].children;
+      }
+      const cell = h(child, cellElementName, props, all(h, child));
+      cells.push(cell);
+
+      // clean text elements
+      visit(cell, (n) => {
+        if (n.tagName === 'code') {
+          return SKIP;
+        }
+        if (n.type === 'text') {
+          // eslint-disable-next-line no-param-reassign
+          n.value = n.value.replace(/\r?\n/mg, ' ');
+        }
+        return CONTINUE;
+      });
+    }
+  }
+
+  return h(node, 'tr', cells);
+}
+
+/**
+ * Handles a group (array) of rows. eg the children of a `gtBody`.
+ * @return {HastNode[]} the array of rows
+ */
+function createRows(h, node, cellElementName) {
+  const rows = [];
+  for (const child of node.children) {
+    if (child.type === TYPE_ROW) {
+      rows.push(handleRow(h, child, cellElementName));
+    }
+  }
+  return rows;
+}
+
+/**
+ * Transforms the gridTable to a hast table
+ *
+ * @param {GridTableHandlerOptions} opts
+ * @return {function} A mdast-to-hast handler.
+ */
+export default function gridTableHandler(opts = {}) {
+  const { noHeader } = opts;
+
+  return function handleTable(h, node) {
+    let headerRows = [];
+    let bodyRows = [];
+    let footerRows = [];
+
+    for (const child of node.children) {
+      if (child.type === TYPE_HEADER) {
+        headerRows = createRows(h, child, 'th');
+      } else if (child.type === TYPE_BODY) {
+        bodyRows = createRows(h, child, 'td');
+      } else if (child.type === TYPE_FOOTER) {
+        footerRows = createRows(h, child, 'td');
+      } else if (child.type === TYPE_ROW) {
+        bodyRows.push(handleRow(h, child, 'td'));
+      }
+    }
+
+    let inner;
+    if (noHeader && footerRows.length === 0) {
+      inner = [...headerRows, ...bodyRows];
+    } else {
+      inner = [];
+      if (headerRows.length) {
+        inner.push(h(null, 'thead', headerRows));
+      }
+      if (bodyRows.length) {
+        inner.push(h(null, 'tbody', bodyRows));
+      }
+      if (footerRows.length) {
+        inner.push(h(null, 'tfoot', footerRows));
+      }
+    }
+
+    return h(node, 'table', inner);
+  };
+}

package/src/gridtable/remark-plugin.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2022 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import fromMarkdown from './from-markdown.js';
+import toMarkdown from './to-markdown.js';
+import syntax from './syntax.js';
+
+export default function remarkPlugin(options = {}) {
+  const data = this.data();
+
+  function add(field, value) {
+    /* c8 ignore next 2 */
+    if (data[field]) {
+      data[field].push(value);
+    } else {
+      data[field] = [value];
+    }
+  }
+
+  const opts = {
+    processor: this,
+    ...options,
+  };
+
+  add('micromarkExtensions', syntax(options));
+  add('fromMarkdownExtensions', fromMarkdown(opts));
+  add('toMarkdownExtensions', toMarkdown(options));
+}

package/src/gridtable/syntax.js

@@ -0,0 +1,352 @@
+/*
+ * Copyright 2022 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+/* eslint-disable no-use-before-define,no-underscore-dangle,no-param-reassign */
+import { codes } from 'micromark-util-symbol/codes.js';
+import { types } from 'micromark-util-symbol/types.js';
+import {
+  markdownLineEnding,
+  markdownSpace,
+} from 'micromark-util-character';
+import {
+  TYPE_BODY, TYPE_CELL, TYPE_HEADER, TYPE_FOOTER, TYPE_TABLE,
+} from './types.js';
+
+// the cell divider: | or +
+const TYPE_CELL_DIVIDER = 'cellDivider';
+
+// a line within a row. can have cells or dividers or both, in case of row spans
+const TYPE_ROW_LINE = 'rowLine';
+
+// the grid divider: - / =
+const TYPE_GRID_DIVIDER = 'gridDivider';
+
+const V_ALIGN_CODES = {
+  [codes.lowercaseV]: 'bottom',
+  [codes.lowercaseX]: 'middle',
+  [codes.caret]: 'top',
+};
+
+function parse() {
+  return {
+    tokenize: tokenizeTable,
+    resolve: resolveTable,
+    resolveAll: resolveAllTable,
+    concrete: true,
+  };
+
+  function tokenizeTable(effects, ok, nok) {
+    // positions of columns
+    const cols = [0];
+    let numRows = 0;
+    let numCols = 0;
+    let colPos = 0;
+    let rowLine = null;
+    let align = '';
+    let valign = '';
+    return start;
+
+    function start(code) {
+      effects.enter(TYPE_TABLE)._cols = cols;
+      effects.enter(TYPE_BODY);
+      return lineStart(code);
+    }
+
+    function lineStart(code) {
+      if (code === codes.plusSign || code === codes.verticalBar) {
+        rowLine = effects.enter(TYPE_ROW_LINE);
+        effects.enter(TYPE_CELL_DIVIDER);
+        effects.consume(code);
+        effects.exit(TYPE_CELL_DIVIDER);
+        colPos = 0;
+        numCols = 0;
+        return cellOrGridStart;
+      }
+      if (numRows < 3) {
+        return nok(code);
+      }
+      effects.exit(TYPE_BODY);
+      effects.exit(TYPE_TABLE);
+      return ok(code);
+    }
+
+    function cellOrGridStart(code) {
+      align = '';
+      valign = '';
+      if (code === codes.dash || code === codes.equalsTo
+        || code === codes.colon || code === codes.greaterThan) {
+        effects.enter(TYPE_GRID_DIVIDER)._colStart = colPos;
+        colPos += 1;
+        if (code === codes.colon) {
+          align = 'left';
+        } else if (code === codes.greaterThan) {
+          align = 'justify';
+        }
+        effects.consume(code);
+        return gridDivider;
+      }
+
+      if (code === codes.eof || markdownLineEnding(code)) {
+        return lineEnd(code);
+      }
+
+      effects.enter(TYPE_CELL)._colStart = colPos;
+      colPos += 1;
+      effects.consume(code);
+
+      if (markdownSpace(code)) {
+        return cellSpace;
+      }
+      return cell;
+    }
+
+    function cellSpace(code) {
+      if (code === codes.eof || markdownLineEnding(code)) {
+        // mark as discarded, will be filtered out in transform
+        effects.exit(TYPE_CELL)._discard = true;
+        return lineEnd(code);
+      }
+      if (markdownSpace(code)) {
+        colPos += 1;
+        effects.consume(code);
+        return cellSpace;
+      }
+      return cell(code);
+    }
+
+    function lineEnd(code) {
+      if (numCols === 0) {
+        return nok(code);
+      }
+      if (markdownLineEnding(code)) {
+        effects.enter(types.lineEnding);
+        effects.consume(code);
+        effects.exit(types.lineEnding);
+      }
+      effects.exit(TYPE_ROW_LINE);
+      if (code === codes.eof) {
+        effects.exit(TYPE_BODY);
+        effects.exit(TYPE_TABLE);
+        return ok(code);
+      }
+      numRows += 1;
+      return lineStart;
+    }
+
+    function gridDivider(code) {
+      colPos += 1;
+      if (code === codes.dash || code === codes.equalsTo) {
+        if (!rowLine._type) {
+          rowLine._type = code;
+        }
+        effects.consume(code);
+        return gridDivider;
+      }
+      if (code === codes.colon) {
+        if (!align) {
+          align = 'right';
+        } else if (align === 'left') {
+          align = 'center';
+        } else {
+          return nok(code);
+        }
+        effects.consume(code);
+        return gridDividerEnd;
+      }
+      if (code === codes.lessThan) {
+        if (align !== 'justify') {
+          return nok(code);
+        }
+        effects.consume(code);
+        return gridDividerEnd;
+      }
+
+      if (V_ALIGN_CODES[code]) {
+        if (valign) {
+          return nok(code);
+        }
+        valign = V_ALIGN_CODES[code];
+        effects.consume(code);
+        return gridDivider;
+      }
+      if (code === codes.plusSign || code === codes.verticalBar) {
+        colPos -= 1;
+        return gridDividerEnd(code);
+      }
+      return nok(code);
+    }
+
+    function gridDividerEnd(code) {
+      if (code !== codes.plusSign && code !== codes.verticalBar) {
+        return nok(code);
+      }
+      // for a super small column, assume dash
+      if (!rowLine._type) {
+        rowLine._type = code.dash;
+      }
+      colPos += 1;
+      // remember cols
+      const idx = cols.indexOf(colPos);
+      if (idx < 0) {
+        cols.push(colPos);
+        cols.sort((c0, c1) => c0 - c1);
+      }
+      const token = effects.exit(TYPE_GRID_DIVIDER);
+      token._colEnd = colPos;
+      token._align = align;
+      token._valign = valign;
+      effects.enter(TYPE_CELL_DIVIDER);
+      effects.consume(code);
+      effects.exit(TYPE_CELL_DIVIDER);
+      numCols += 1;
+      return cellOrGridStart;
+    }
+
+    function cell(code) {
+      colPos += 1;
+      // find existing col
+      if (code === codes.verticalBar || code === codes.plusSign) {
+        const idx = cols.indexOf(colPos);
+        if (idx >= 0) {
+          effects.exit(TYPE_CELL)._colEnd = colPos;
+          effects.enter(TYPE_CELL_DIVIDER);
+          effects.consume(code);
+          effects.exit(TYPE_CELL_DIVIDER);
+          numCols += 1;
+          return cellOrGridStart;
+        }
+        effects.consume(code);
+        return cell;
+      }
+      if (code === codes.eof) {
+        // row with cells never terminate eof
+        return nok(code);
+      }
+
+      effects.consume(code);
+      return (code === codes.backslash)
+        ? cellEscaped
+        : cell;
+    }
+
+    function cellEscaped(code) {
+      if (code === codes.backslash || code === codes.verticalBar || code === codes.plusSign) {
+        colPos += 1;
+        effects.consume(code);
+        return cell;
+      }
+      return cell(code);
+    }
+  }
+
+  function resolveHeaderAndFooter(events, context) {
+    // detect headers:
+    // no `=` lines -> only body
+    // 1 `=` line -> header + body
+    // 2 `=` lines -> header + body + footer
+    const fatLines = [];
+    let bodyStart = -1; // should default to 1. but just be sure
+
+    for (let idx = 0; idx < events.length; idx += 1) {
+      const [e, node] = events[idx];
+      const { type } = node;
+      if (type === TYPE_BODY) {
+        if (e === 'enter') {
+          bodyStart = idx;
+        } else {
+          // eslint-disable-next-line prefer-const
+          let [hdrIdx, ftrIdx] = fatLines;
+          const bdy = node;
+          if (hdrIdx > bodyStart + 1) {
+            // insert header above body
+            const hdr = {
+              type: TYPE_HEADER,
+              start: bdy.start,
+              end: events[hdrIdx][1].end,
+            };
+            bdy.start = hdr.end;
+            events[bodyStart][1] = hdr;
+            events.splice(
+              hdrIdx,
+              0,
+              ['exit', hdr, context],
+              ['enter', bdy, context],
+            );
+            idx += 2;
+            ftrIdx += 2;
+          }
+
+          if (ftrIdx) {
+            // insert footer below body
+            const ftr = {
+              type: TYPE_FOOTER,
+              start: events[ftrIdx][1].start,
+              end: bdy.end,
+            };
+            bdy.end = ftr.start;
+            events.splice(
+              ftrIdx,
+              0,
+              ['exit', bdy, context],
+              ['enter', ftr, context],
+            );
+            idx += 2;
+            events[idx][1] = ftr;
+          }
+        }
+      } else if (type === TYPE_ROW_LINE && e === 'enter' && node._type === codes.equalsTo) {
+        fatLines.push(idx);
+      }
+    }
+    return events;
+  }
+
+  function resolveTable(events, context) {
+    // remove discarded
+    events = events.filter(([, node]) => !node._discard);
+
+    events = resolveHeaderAndFooter(events, context);
+    // let i = 0;
+    // for (const [d, { type }] of events) {
+    //   if (d === 'exit') {
+    //     i -= 2;
+    //   }
+    //   console.log(' '.repeat(i), d, type);
+    //   if (d === 'enter') {
+    //     i += 2;
+    //   }
+    // }
+    return events;
+  }
+
+  function resolveAllTable(events, context) {
+    // since we create a detached parser for each cell content later (in from-markdown.js)
+    // we need to remember the definitions of the overall document. otherwise the cell parsers
+    // would not detect the image and link references.
+    const { defined } = context.parser;
+
+    // find all grid tables and remember the definitions
+    for (const [evt, node] of events) {
+      if (evt === 'enter' && node.type === TYPE_TABLE) {
+        node._definitions = defined;
+      }
+    }
+    return events;
+  }
+}
+
+export default function create(options = {}) {
+  return {
+    flow: {
+      [codes.plusSign]: parse(options),
+    },
+  };
+}