✨ Add csv-table directive

.changeset/silent-dancers-burn.md

@@ -0,0 +1,5 @@
+---
+"myst-directives": minor
+---
+
+Add the csv-table directive

docs/directives.md

@@ -18,6 +18,9 @@ description: A full list of the directives included in MyST Markdown by default.
 :::{myst:directive} code-cell
 :::
 
+:::{myst:directive} csv-table
+:::
+
 :::{myst:directive} dropdown
 :::
 

docs/tables.md

@@ -36,6 +36,11 @@ You can use the {myst:directive}`table` directive to add a caption to a markdown
 :::
 ```
 
+```{note}
+You may have inline markdown in the table caption, however, if it includes backticks, you must use a [colon fence](#example-fence).
+```
+
+
 ## List Tables
 
 ````{myst}
@@ -52,11 +57,19 @@ You can use the {myst:directive}`table` directive to add a caption to a markdown
 ```
 ````
 
-```{note}
-You may have inline markdown in the table caption, however, if it includes backticks, you must use a [colon fence](#example-fence).
-```
+## CSV Tables
 
+````{myst}
+```{csv-table} This table title
+:header-rows: 1
+:label: example-table
+
+Training, Validation
+0,        5
+13720,    2744
+```
+````
 ## Notebook outputs as tables
 
 You can embed Jupyter Notebook outputs as tables.
-See [](reuse-jupyter-outputs.md) for more information.
+See [](reuse-jupyter-outputs.md) for more information.

packages/myst-directives/package.json

@@ -33,6 +33,7 @@
   },
   "dependencies": {
     "classnames": "^2.3.2",
+    "csv-parse": "^5.5.5",
     "js-yaml": "^4.1.0",
     "myst-common": "^1.2.0",
     "myst-spec-ext": "^1.2.0",

packages/myst-directives/src/index.ts

@@ -7,7 +7,7 @@ import { figureDirective } from './figure.js';
 import { iframeDirective } from './iframe.js';
 import { imageDirective } from './image.js';
 import { includeDirective } from './include.js';
-import { tableDirective, listTableDirective } from './table.js';
+import { csvTableDirective, tableDirective, listTableDirective } from './table.js';
 import { asideDirective } from './aside.js';
 import { glossaryDirective } from './glossary.js';
 import { mathDirective } from './math.js';
@@ -21,6 +21,7 @@ import { rawDirective } from './raw.js';
 export const defaultDirectives = [
   admonitionDirective,
   bibliographyDirective,
+  csvTableDirective,
   codeDirective,
   codeCellDirective,
   dropdownDirective,
@@ -51,7 +52,7 @@ export { figureDirective } from './figure.js';
 export { iframeDirective } from './iframe.js';
 export { imageDirective } from './image.js';
 export { includeDirective } from './include.js';
-export { listTableDirective, tableDirective } from './table.js';
+export { csvTableDirective, listTableDirective, tableDirective } from './table.js';
 export { asideDirective } from './aside.js';
 export { mathDirective } from './math.js';
 export { mdastDirective } from './mdast.js';

packages/myst-directives/src/table.ts

@@ -1,6 +1,14 @@
-import type { DirectiveSpec, DirectiveData, GenericNode } from 'myst-common';
+import type {
+  DirectiveSpec,
+  DirectiveData,
+  DirectiveContext,
+  GenericNode,
+  GenericParent,
+} from 'myst-common';
 import { fileError, normalizeLabel, RuleId } from 'myst-common';
 import type { VFile } from 'vfile';
+import { parse } from 'csv-parse/sync';
+import { select } from 'unist-util-select';
 
 export const tableDirective: DirectiveSpec = {
   name: 'table',
@@ -162,3 +170,137 @@ export const listTableDirective: DirectiveSpec = {
     return [container];
   },
 };
+
+/**
+ * Parse a CSV-table comprising of (inline) MyST Markdown
+ *
+ * @param data - CSV string
+ * @param opts - directive options
+ * @param ctx - directive evaluation context
+ */
+function parseCSV(
+  data: string,
+  opts: DirectiveData['options'] | undefined,
+  ctx: DirectiveContext,
+): GenericParent[][] {
+  const delimiter = (opts?.delimiter ?? ',') as string;
+  const records = parse(data, {
+    delimiter,
+    ltrim: !opts?.keepspace,
+    escape: (opts?.escape ?? delimiter) as string,
+    quote: (opts?.quote ?? '"') as string,
+  });
+
+  return records.map((record: any, recordIndex: number) => {
+    return record.map((cell: string) => {
+      const mdast = ctx.parseMyst(cell, recordIndex);
+      const paragraph = select('*:root > paragraph:only-child', mdast);
+
+      if (paragraph === undefined) {
+        throw new Error(`Expected a root element containing a paragraph, found: ${cell}`);
+      }
+      return paragraph;
+    });
+  });
+}
+
+export const csvTableDirective: DirectiveSpec = {
+  name: 'csv-table',
+  arg: {
+    type: 'myst',
+  },
+  options: {
+    label: {
+      type: String,
+      alias: ['name'],
+    },
+    header: {
+      type: String,
+      // nonnegative int
+    },
+
+    'header-rows': {
+      type: Number,
+      // nonnegative int
+    },
+    class: {
+      type: String,
+      // class_option: list of strings?
+      doc: `CSS classes to add to your table. Special classes include:
+
+- \`full-width\`: changes the table environment to cover two columns in LaTeX`,
+    },
+    align: {
+      type: String,
+      // choice(['left', 'center', 'right'])
+    },
+    delim: {
+      type: String,
+    },
+    escape: {
+      type: String,
+    },
+    keepspace: {
+      type: Boolean,
+    },
+    quote: {
+      type: String,
+    },
+  },
+  body: {
+    type: String,
+    required: true,
+  },
+  run(data: DirectiveData, vfile: VFile, ctx: DirectiveContext): GenericNode[] {
+    const { label, identifier } = normalizeLabel(data.options?.label as string | undefined) || {};
+
+    const rows: GenericParent[] = [];
+
+    if (data.options?.header !== undefined) {
+      const headerCells = parseCSV(data.options.header as string, data.options, ctx);
+      rows.push(
+        ...headerCells.map((parsedRow) => ({
+          type: 'tableRow',
+          children: parsedRow.map((parsedCell) => ({
+            type: 'tableCell',
+            header: true,
+            children: parsedCell.children,
+          })),
+        })),
+      );
+    }
+    const cells = parseCSV(data.body as string, data.options, ctx);
+
+    let headerCount = (data.options?.['header-rows'] as number) || 0;
+    rows.push(
+      ...cells.map((parsedRow) => {
+        const row = {
+          type: 'tableRow',
+          children: parsedRow.map((parsedCell) => ({
+            type: 'tableCell',
+            header: headerCount > 0 ? true : undefined,
+            children: parsedCell.children,
+          })),
+        };
+
+        headerCount -= 1;
+        return row;
+      }),
+    );
+    const table = {
+      type: 'table',
+      align: data.options?.align,
+      children: rows,
+    };
+    const container = {
+      type: 'container',
+      kind: 'table',
+      identifier: identifier,
+      label: label,
+      class: data.options?.class,
+      children: [...(data.arg as GenericNode[]), table],
+    };
+
+    return [container];
+  },
+};