@adobe/helix-markdown-support 3.1.8 → 4.0.0

package/.circleci/config.yml

@@ -1,35 +1,26 @@
 version: 2.1
 executors:
-  node14:
+  node16:
     docker:
-      - image: circleci/node:14
-    environment:
-      NPM_CONFIG_PREFIX: ~/.npm-global
+      - image: cimg/node:16.16
+
+orbs:
+  codecov: codecov/codecov@3.2.3
 
 commands:
   setup:
     steps:
       - checkout
-      - restore_cache:
-          keys:
-            - v1-dependencies-{{ arch }}-{{ checksum "package-lock.json" }}
-      - run:
-          name: install latest npm
-          command: sudo npm -g install npm
       - run:
           name: Installing Dependencies
           command: npm ci
-      - save_cache:
-          paths:
-            - node_modules
-          key: v1-dependencies-{{ arch }}-{{ checksum "package-lock.json" }}
       - run:
           name: prepare test git user
           command: git config --global user.email "circleci@example.com" && git config --global user.name "CircleCi Build"
 
 jobs:
   build:
-    executor: node14
+    executor: node16
 
     steps:
       - setup
@@ -37,14 +28,12 @@ jobs:
       - run:
           name: Lint
           command: npm run lint
-
       - run:
           name: Getting Code Coverage
-          command: npm run test-ci
-
+          command: npm run test
+      - codecov/upload
       - store_test_results:
           path: junit
-
       - store_artifacts:
           path: junit
 

package/.eslintrc.cjs

@@ -23,5 +23,6 @@ module.exports = {
   },
   rules: {
     'import/extensions': 0,
+    'import/prefer-default-export': 0,
   },
 };

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [4.0.0](https://github.com/adobe/helix-markdown-support/compare/v3.1.8...v4.0.0) (2022-09-02)
+
+
+### Features
+
+* markdown gridtables ([1f3d7d2](https://github.com/adobe/helix-markdown-support/commit/1f3d7d27045c3d31556c73b2631fc7b1b910ef46))
+
+
+### BREAKING CHANGES
+
+* the remarkMatter plugin export changed.
+
 ## [3.1.8](https://github.com/adobe/helix-markdown-support/compare/v3.1.7...v3.1.8) (2022-07-28)
 
 

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@adobe/helix-markdown-support",
-  "version": "3.1.8",
+  "version": "4.0.0",
   "description": "Helix Markdown Support",
   "type": "module",
   "scripts": {
     "test": "c8 mocha",
-    "test-ci": "c8 mocha && codecov",
     "lint": "eslint .",
     "semantic-release": "semantic-release",
     "prepare": "husky install"
@@ -21,14 +20,21 @@
   },
   "homepage": "https://github.com/adobe/helix-markdown-support#readme",
   "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./gridtable": "./src/gridtable/index.js",
+    "./matter": "./src/matter/index.js"
+  },
   "dependencies": {
     "hast-util-to-html": "8.0.3",
     "js-yaml": "4.1.0",
-    "mdast-util-to-hast": "12.1.2",
+    "mdast-util-from-markdown": "1.2.0",
+    "mdast-util-to-hast": "12.2.1",
+    "mdast-util-to-markdown": "1.3.0",
     "micromark-util-character": "1.1.0",
     "micromark-util-symbol": "1.0.1",
     "unist-util-find": "1.0.2",
-    "unist-util-visit": "4.1.0"
+    "unist-util-visit": "4.1.1"
   },
   "mocha": {
     "spec": "test/**/*.test.js",
@@ -40,13 +46,15 @@
   "peerDependencies": {
     "unified": "10.x"
   },
+  "engines": {
+    "node": ">=14"
+  },
   "devDependencies": {
     "@adobe/eslint-config-helix": "1.3.2",
     "@semantic-release/changelog": "6.0.1",
     "@semantic-release/git": "10.0.1",
     "c8": "7.12.0",
-    "codecov": "3.8.3",
-    "eslint": "8.20.0",
+    "eslint": "8.23.0",
     "eslint-plugin-header": "3.1.1",
     "eslint-plugin-import": "2.26.0",
     "husky": "8.0.1",
@@ -55,10 +63,11 @@
     "mdast-builder": "1.1.1",
     "mocha": "10.0.0",
     "mocha-multi-reporters": "1.5.1",
+    "rehype-format": "4.0.1",
     "remark-gfm": "3.0.1",
     "remark-parse": "10.0.1",
     "remark-stringify": "10.0.2",
-    "semantic-release": "19.0.3",
+    "semantic-release": "19.0.5",
     "unified": "10.1.2",
     "unist-util-inspect": "7.0.1"
   },

package/src/gridtable/README.md

@@ -0,0 +1,207 @@
+# Grid Tables
+
+## Overview
+
+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 |
++-------+  +-------+  +-------+
+```
+
+## Syntax
+
+```ebfn
+
+gridTable := gridLine cellLine+ gridLine;
+gridLine := gridCell+ "+";
+cellLine := ( gridCell | cellContent )+ ( "+" | "|" );   
+gridCell := "+" alignMarkerStart? ("-" | "=")+ vAlignMarker? ("-" | "=")* alignMarkerEnd?;
+cellContent := ( "+" | "|" ) " " content " " ;
+alignMarkerStart := ":" | ">";
+alignMarkerEnd   := ":" | "<";
+vAlignMarker     := "^" | "v" | "x"
+```
+
+## MDAST Syntax tree
+
+The following interfaces are added to **[mdast][]** by this utility.
+
+### Nodes
+
+#### `GridTable`
+
+```idl
+interface GridTable <: Parent {
+  type: "gridTable"
+  children: [GridTableHeader|GridTableBody|GridTableFooter]
+}
+```
+
+#### `GridTableHeader`
+
+```idl
+interface GridTableHeader <: Parent {
+  type: "gtHead"
+  children: [GridTableRow]
+}
+```
+
+#### `GridTableBody`
+
+```idl
+interface GridTableBody <: Parent {
+  type: "gtBody"
+  children: [GridTableRow]
+}
+```
+
+#### `GridTableFoot`
+
+```idl
+interface GridTableFooter <: Parent {
+  type: "gtFoot"
+  children: [GridTableRow]
+}
+```
+
+#### `GridTableRow`
+
+```idl
+interface GridTableRow <: Parent {
+  type: "gtRow"
+  children: [GridTableCell]
+}
+```
+
+#### `GridTableCell`
+
+```idl
+interface GridTableCell <: Parent {
+  type: "gtCell"
+  colSpan: number >= 1
+  rowSpan: number >= 1
+  align: alignType
+  valign: valignType
+  children: [MdastContent]
+}
+```
+
+**GridTableCell** ([**Parent**][dfn-parent]) represents a header cell in a
+[**GridTable**][dfn-table], if its parent is a [*gridTableHead*][term-head], or a data
+cell otherwise.
+
+**GridTableCell** can be used where [**gridTableRow**][dfn-row-content] content is expected.
+Its content model is [**mdast**][dfn-phrasing-content] content, allowing full mdast documents.
+
+### Enumeration
+
+#### `alignType`
+
+```idl
+enum alignType {
+  "left" | "right" | "center" | "justify" | null
+}
+```
+
+#### `valignType`
+
+```idl
+enum alignType {
+  "top" | "bottom" | "middle" | null
+}
+```
+
+## Usage
+
+### Parsing with unified
+
+```js
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import { remarkGridTable } from '@adobe/helix-markdown-support/gridtable';
+
+const mdast = unified()
+  .use(remarkParse)
+  .use(remarkGridTable)
+  .parse(markdown);
+```
+
+### Generating HAST
+
+```js
+import { toHast, defaultHandlers } from 'mdast-util-to-hast';
+import { mdast2hastGridTableHandler, TYPE_TABLE } from '@adobe/helix-markdown-support/gridtable';
+
+const hast = toHast(mdast, {
+  handlers: {
+    ...defaultHandlers,
+    [TYPE_TABLE]: mdast2hastGridTableHandler(),
+  },
+  allowDangerousHtml: true,
+});
+```
+

package/src/gridtable/from-markdown.js

@@ -0,0 +1,273 @@
+/*
+ * 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-underscore-dangle */
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { CONTINUE, visit } from 'unist-util-visit';
+import {
+  TYPE_BODY, TYPE_CELL, TYPE_HEADER, TYPE_FOOTER, TYPE_ROW, TYPE_TABLE,
+} from './types.js';
+
+function unescapeDelimsInCode(tree) {
+  visit(tree, (node) => {
+    if (node.type === 'inlineCode' || node.type === 'code') {
+      // eslint-disable-next-line no-param-reassign
+      node.value = node.value.replace(/\\([+|])/gm, '$1');
+    }
+    return CONTINUE;
+  });
+}
+
+function multiline(lines) {
+  // remove empty trailing lines
+  while (lines.length > 0 && lines[lines.length - 1].match(/^\s*$/)) {
+    lines.pop();
+  }
+
+  // calculate common indent
+  const prefixLen = lines
+    .filter((line) => !line.match(/^\s*$/))
+    .map((line) => line.match(/^ */)[0].length)
+    .reduce((min, len) => Math.min(len, min), Infinity);
+
+  // remove prefix
+  return lines
+    .map((line) => line.substring(prefixLen).trimEnd());
+}
+
+function getColSpan(info, token) {
+  const i0 = info.cols.indexOf(token._colStart);
+  const i1 = info.cols.indexOf(token._colEnd);
+  return i1 - i0;
+}
+
+function enterTable(token) {
+  this.enter({ type: TYPE_TABLE, children: [] }, token);
+  this.setData('tableInfo', {
+    // the column positions of the table
+    cols: token._cols,
+    // the current column
+    colPos: 0,
+    // list of all cells
+    allCells: [],
+    // cells that are still open via rowSpan
+    pendingCells: [],
+    // the current cells of a row
+    cells: [],
+    // the grid dividers use for align the cells
+    dividers: [],
+    // the link/image reference definitions
+    definitions: token._definitions,
+  });
+}
+
+function createExitTable(options) {
+  const { processor } = options;
+
+  return function exitTable(token) {
+    // render cells
+    const info = this.getData('tableInfo');
+    for (const cell of info.allCells) {
+      const {
+        node, lines, colSpan, rowSpan,
+        align, valign,
+      } = cell;
+
+      // add fake definitions...
+      const sanitizedLines = multiline(lines);
+      for (const def of info.definitions) {
+        sanitizedLines.push('');
+        sanitizedLines.push(`[${def}]: dummy`);
+      }
+      const cellContent = sanitizedLines.join('\n');
+
+      const tree = fromMarkdown(cellContent, {
+        extensions: processor.data('micromarkExtensions'),
+        mdastExtensions: processor.data('fromMarkdownExtensions'),
+      });
+
+      // remove previously added definitions
+      for (let i = 0; i < tree.children.length; i += 1) {
+        const child = tree.children[i];
+        if (child.type === 'definition' && info.definitions.includes(child.label)) {
+          tree.children.splice(i, 1);
+          i -= 1;
+        }
+      }
+
+      // remove escaped pipes and plusses in code
+      unescapeDelimsInCode(tree);
+
+      node.children = tree.children;
+      if (colSpan > 1) {
+        node.colSpan = colSpan;
+      }
+      if (rowSpan > 1) {
+        node.rowSpan = rowSpan;
+      }
+      if (align) {
+        node.align = align;
+      }
+      if (valign) {
+        node.valign = valign;
+      }
+    }
+    this.exit(token);
+  };
+}
+
+function enter(token) {
+  this.enter({ type: token.type, children: [] }, token);
+}
+
+function enterCell() {
+  this.buffer();
+}
+
+function exitCell(token) {
+  this.config.enter.data.call(this, token);
+  this.config.exit.data.call(this, token);
+  const data = this.resume();
+  const info = this.getData('tableInfo');
+  const colSpan = getColSpan(info, token);
+
+  let cell = info.pendingCells[info.colPos];
+
+  // open rowspan if we are on a divider line
+  if (info.isDivider) {
+    if (!cell) {
+      cell = info.cells[info.colPos];
+      info.pendingCells[info.colPos] = cell;
+    }
+    if (!cell) {
+      // throw Error('no matching rowspan');
+    } else {
+      cell.rowSpan += 1;
+    }
+  }
+
+  // if a rowspan is open, append to its cell
+  if (cell) {
+    cell.lines.push(data);
+    info.colPos += colSpan;
+    return;
+  }
+
+  // otherwise append to regular cell
+  cell = info.cells[info.colPos];
+  if (!cell) {
+    const div = info.dividers[info.colPos];
+    cell = {
+      rowSpan: 1,
+      colSpan,
+      align: div?._align,
+      valign: div?._valign,
+      node: {
+        type: TYPE_CELL,
+      },
+      lines: [],
+    };
+    info.cells[info.colPos] = cell;
+    info.allCells.push(cell);
+  }
+  cell.lines.push(data);
+  info.colPos += colSpan;
+}
+
+function enterGridDivider(token) {
+  const info = this.getData('tableInfo');
+  // clear pending rowspans and set divider info
+  let colSpan = getColSpan(info, token);
+  while (colSpan > 0) {
+    colSpan -= 1;
+    info.pendingCells[info.colPos] = null;
+    info.dividers[info.colPos] = token;
+    info.colPos += 1;
+  }
+}
+
+function enterRowLine(token) {
+  const info = this.getData('tableInfo');
+  info.isDivider = token._type;
+  info.colPos = 0;
+  if (info.isDivider) {
+    info.dividers = [];
+  }
+}
+
+function commitRow(info) {
+  // create fake token for 'gtRow'
+  const rowToken = {
+    type: TYPE_ROW,
+    start: { line: 0, column: 0, offset: 0 },
+    end: { line: 0, column: 0, offset: 0 },
+  };
+  this.enter({ type: TYPE_ROW, children: [] }, rowToken);
+
+  // emit cells
+  for (const cell of info.cells) {
+    if (cell) {
+      const cellToken = {
+        type: TYPE_CELL,
+        start: { line: 0, column: 0, offset: 0 },
+        end: { line: 0, column: 0, offset: 0 },
+      };
+      this.enter(cell.node, cellToken);
+      this.exit(cellToken);
+    }
+  }
+
+  this.exit(rowToken);
+  // eslint-disable-next-line no-param-reassign
+  info.cells = [];
+}
+
+function exitHeader(token) {
+  const info = this.getData('tableInfo');
+  // commit row  has some cells
+  if (info.cells.length) {
+    commitRow.call(this, info);
+    // also close all rowspans.
+    info.pendingCells = [];
+  }
+  this.exit(token);
+}
+
+function exitRowLine() {
+  const info = this.getData('tableInfo');
+  // commit row if on a divider and has some cells
+  if (info.isDivider && info.cells.length) {
+    commitRow.call(this, info);
+  }
+}
+
+// eslint-disable-next-line no-unused-vars
+export default function handler(options = {}) {
+  return {
+    enter: {
+      [TYPE_TABLE]: enterTable,
+      [TYPE_HEADER]: enter,
+      [TYPE_BODY]: enter,
+      [TYPE_FOOTER]: enter,
+      [TYPE_CELL]: enterCell,
+      gridDivider: enterGridDivider,
+      rowLine: enterRowLine,
+    },
+    exit: {
+      [TYPE_TABLE]: createExitTable(options),
+      [TYPE_HEADER]: exitHeader,
+      [TYPE_BODY]: exitHeader,
+      [TYPE_FOOTER]: exitHeader,
+      [TYPE_CELL]: exitCell,
+      rowLine: exitRowLine,
+    },
+  };
+}