markdown-it-adv-table 0.1.2 → 0.2.0

package/README.md

@@ -1,18 +1,26 @@
 
 # markdown-it-adv-table
 
-A [markdown-it](https://www.npmjs.com/package/markdown-it) plugin to enable advanced table rendering in Markdown. The custom syntax allows to create complex tables supporting:
+A [markdown-it](https://www.npmjs.com/package/markdown-it) plugin for advanced table rendering. 
 
-- Rowspan and colspan for merged cells
-- Custom column widths
-- Horizontal cell alignment
-- Table styling with css classes
-- Header rows and columns (using `<th>`)
-- Multiple blocks and nested markdown within cells
+This plugin adds custom table syntaxes to render complex tables easier. 
 
-## Install
+- "flat-table" syntax
+- "csv-table" syntax
+- "tsv-table" syntax
 
-```bash
+The "flat-table" syntax allows to:
+
+- Set Rowspan and colspan for spanning cells
+- Set column width
+- Set horizontal text alignment
+- Set css classes for table styling
+- Define Header rows and columns
+- Allow writing markdown inside the cells (nested document)
+
+## Installation
+
+```sh
 npm install markdown-it-adv-table
 ```
 
@@ -25,11 +33,37 @@ md.use(advTable);
 const html = md.render("text...");
 ```
 
-## Documentation
+<table>
+<tr>
+    <th>Plugin</th>
+    <th>LangName</th>
+    <th>Behavior</th>
+</tr>
+<tr>
+    <td><code>advTable</code></td>
+    <td>table*</td>
+    <td>Installs an all-unified plugin</td>
+</tr>
+<tr>
+    <td><code>flatTable</code></td>
+    <td>flat-table</td>
+    <td>parse flat-table syntax</td>
+</tr>
+<tr>
+    <td><code>csvTable</code></td>
+    <td>csv-table</td>
+    <td>render csv as table</td>
+</tr>
+<tr>
+    <td><code>tsvTable</code></td>
+    <td>tsv-table</td>
+    <td>render tsv as table</td>
+</tr>
+</table>
 
-To Be Documented
+## Usage
 
-## Examples
+Use fenced code block for the table data.
 
 ``````
 ```table cols=4 header-rows=2 header-cols=1
@@ -54,6 +88,7 @@ c3| Q1 Sales
 | $3,500
 | $4,000
 | $4,200
+```
 ``````
 
 <table>
@@ -90,7 +125,134 @@ c3| Q1 Sales
   </tbody>
 </table>
 
+## Documentation
+
+The table is expressed in a fenced code block. 
+
+- A line that starts with `|` starts a new cell.
+- The cell content is parsed as Markdown.
+- The cell content spans until the next cell marker.
+
+A cell marker can include directives that control the cell’s properties.
+
+
+### TableSpec (Table Definition)
+
+The [info-string](https://spec.commonmark.org/0.31.2/#info-string) of the fenced code block is parsed as TableSpec.
+
+<table>
+<tr>
+    <th>Key</th>
+    <th>Type</th>
+    <th>Value</th>
+</tr>
+<tr>
+    <td>cols</td>
+    <td>number | string</td>
+    <td>
+        <p>Define number of columns.</p>
+        <p>If the value is a string literal, it is a <a href="#colspec"><code>ColSpec</code></a>.</p>
+        <pre>cols=3           // 3 columns
+cols="1,1,2"     // 3 columns, 1:1:2 ratio</pre>
+  </td>
+</tr>
+<tr>
+    <td>header-cols</td>
+    <td>number</td>
+  <td>Number of header columns (rendered as &lt;th&gt;)</td>
+</tr>
+<tr>
+    <td>header-rows</td>
+    <td>number</td>
+  <td>Number of header rows (rendered as &lt;thead&gt; with &lt;th&gt;)</td>
+</tr>
+<tr>
+    <td>class</td>
+    <td>string</td>
+  <td>Table class names (space- or comma-separated)</td>
+</tr>
+<tr>
+    <td>width</td>
+    <td>number | string</td>
+  <td>Table width.</td>
+</tr>
+<tr>
+    <td>format</td>
+    <td>string</td>
+    <td>
+        <p>Use alternative table syntax. </p>
+        <ul>
+            <li><code>csv</code> : parse text as csv</li>
+            <li><code>tsv</code> : parse text as tsv</li>
+        </ul>
+    </td>
+</tr>
+</table>
+
+<h3 id="colspec">ColSpec (Column Definition)</h3>
+
+<code>ColSpec</code> is a comma-separated set-of-directives to control the column's properties.
+
+    "1,1,1"            3 columns, 1:1:1 ratio
+    "30%,15,30,60"     4 columns, 3:1:2:4 ratio
+    "<100px,,>25%"     3 columns, 100px-auto-25% with alignment directives
+
+<table>
+<tr>
+    <th>Directive</th>
+    <th>Description</th>
+</tr>
+<tr>
+    <td>size[unit]</td>
+    <td>
+        <p>Set column width.  Any css units can be used.</p>
+        <p>If the unit is omitted, the value represents the weight of the column. The plugin calculates the column width by dividing up the remaining space, based on its weight.</p>
+        <pre>"1,1,2"     = "25%,25%,50%"       (Eq = calc(100% * x / 4))
+"20%,1,1,2" = "20%,20%,20%,40%"   (Eq = calc( 80% * x / 4))</pre>
+        <p>If the size is empty or invalid, the width is unset. The weight of the unsized(auto) column defaults to 1.</p>
+        <p><small>NOTE: The actual width is calculated by the HTML engine, respecting the column's minimum content width.</small></p>
+    </td>
+</tr>
+<tr>
+    <td>&lt;<br>^<br>&gt;</td>
+    <td>
+    Left-aligned<br>
+    Center-aligned<br>
+    Right-aligned<br>
+    </td>
+</tr>
+</table>
+
+
+
+### Cell Directives (Cell Definition)
+
+<table>
+<tr>
+    <th>Syntax</th>
+    <th>Description</th>
+</tr>
+<tr>
+    <td>c2, c{\d+}</td>
+    <td>Set colspan</td>
+</tr>
+<tr>
+    <td>r2, r{\d+}</td>
+    <td>Set rowspan</td>
+</tr>
+<tr>
+    <td>&lt;<br>^<br>&gt;</td>
+    <td>Left align<br>Center align<br>Right align</td>
+</tr>
+<tr>
+    <td>h</td>
+  <td>Use &lt;th&gt; instead of &lt;td&gt;</td>
+</tr>
+</table>
+
+
 
+## More Examples
 
 
 ``````

package/lib/fence.js

@@ -65,15 +65,23 @@ export function fence_custom(names, parser) {
         }
         len = state.sCount[startLine];
         state.line = nextLine + (haveEndMarker ? 1 : 0);
-        if (parser !== undefined) {
-            parser(params, state, startLine, nextLine);
-        }
-        else {
+        const parseDefault = () => {
             const token = state.push("fence", "code", 0);
             token.info = params;
             token.content = state.getLines(startLine + 1, nextLine, len, true);
             token.markup = markup;
             token.map = [startLine, state.line];
+        };
+        if (parser !== undefined) {
+            try {
+                parser(params, state, startLine, nextLine);
+            }
+            catch {
+                parseDefault();
+            }
+        }
+        else {
+            parseDefault();
         }
         return true;
     };

package/lib/flat-table.js

@@ -14,7 +14,8 @@ export class FlatTableParser {
         return new FlatTableParser(tableSpec);
     }
     parse(state, startLine, endLine) {
-        const builder = new TableBuilder(state, this._tableSpec);
+        const md = state.md;
+        const builder = TableBuilder.newLocal(state, this._tableSpec);
         builder.startTable();
         let currentLine = startLine;
         while (currentLine < endLine) {
@@ -29,7 +30,6 @@ export class FlatTableParser {
                     currentLine++;
                 }
                 const cellEnd = currentLine;
-                const md = state.md;
                 const cellIndent = FlatTableParser.getCellIndent(state, line);
                 const cellSpec = FlatTableParser.cellspec(line);
                 const cellAttr = FlatTableParser.parseCellspec(cellSpec);
@@ -54,6 +54,7 @@ export class FlatTableParser {
             }
         }
         builder.endTable();
+        state.tokens.push(...builder.state.tokens);
     }
     getline(state, lineNumber) {
         return state.getLines(lineNumber, lineNumber + 1, state.blkIndent, false);

package/lib/index.d.ts

@@ -1,19 +1,11 @@
-import { PluginWithOptions } from "markdown-it";
+import { PluginSimple, PluginWithOptions } from "markdown-it";
 import { Parser } from "./fence.js";
 export interface PluginOption {
-    names: {
-        adv: string;
-        flat: string;
-        csv: string;
-        tsv: string;
-    };
-}
-export interface PluginOptionSingle {
     name: string;
 }
-export declare function createParser(option: PluginOption): Parser;
+export declare function unifiedParser(option: PluginOption): Parser;
 export declare const advTable: PluginWithOptions<PluginOption>;
-export declare const flatTable: PluginWithOptions<PluginOptionSingle>;
-export declare const csvTable: PluginWithOptions<PluginOptionSingle>;
-export declare const tsvTable: PluginWithOptions<PluginOptionSingle>;
+export declare const flatTable: PluginSimple;
+export declare const csvTable: PluginSimple;
+export declare const tsvTable: PluginSimple;
 export default advTable;

package/lib/index.js

@@ -4,29 +4,16 @@ import { debug } from "./debug.js";
 import { fence_custom } from "./fence.js";
 import { FlatTableParser } from "./flat-table.js";
 import { merge } from "./merge.js";
-const defaultOptions = {
-    names: {
-        adv: "table",
-        flat: "flat-table",
-        csv: "csv-table",
-        tsv: "tsv-table"
-    }
+const langNames = {
+    adv: "table",
+    flat: "flat-table",
+    csv: "csv-table",
+    tsv: "tsv-table",
 };
-const plainNames = {
-    adv: "",
-    flat: "",
-    csv: "",
-    tsv: "",
+const defaultOption = {
+    name: langNames.adv,
 };
-function getAllNames(option) {
-    return [
-        option.names.adv,
-        option.names.flat,
-        option.names.csv,
-        option.names.tsv
-    ];
-}
-export function createParser(option) {
+export function unifiedParser(option) {
     return (info, state, startLine, endLine) => {
         if (debug.isEnabled()) {
             debug(">> table parse start");
@@ -49,52 +36,49 @@ export function createParser(option) {
         }
         const lang = info.slice(0, info.search(/\s|$/));
         const params = info.slice(lang.length + 1);
-        if (lang === option.names.adv) {
+        if (lang === option.name) {
             const parser = new AdvTableParser(params);
             parser.parse(state, startLine + 1, endLine);
         }
-        else if (lang === option.names.flat) {
-            const parser = FlatTableParser.new(info, state, startLine + 1, endLine);
+        else if (lang === langNames.flat) {
+            const parser = FlatTableParser.new(params, state, startLine + 1, endLine);
             parser.parse(state, startLine + 1, endLine);
         }
-        else if (lang === option.names.csv) {
+        else if (lang === langNames.csv) {
             const parser = CsvTableParser.new(params, ",");
             parser.parse(state, startLine + 1, endLine);
         }
-        else if (lang === option.names.tsv) {
+        else if (lang === langNames.tsv) {
             const parser = CsvTableParser.new(params, "\t");
             parser.parse(state, startLine + 1, endLine);
         }
     };
 }
 export const advTable = (md, option) => {
-    const opts = merge(defaultOptions, option);
-    const parser = createParser(opts);
-    const rule = fence_custom(getAllNames(opts), parser);
+    const opts = merge(defaultOption, option);
+    const awareNames = [
+        option?.name ?? langNames.adv,
+        langNames.flat,
+        langNames.csv,
+        langNames.tsv
+    ];
+    const parser = unifiedParser(opts);
+    const rule = fence_custom(awareNames, parser);
     md.block.ruler.before("fence", "adv_table", rule);
 };
-export const flatTable = (md, option) => {
-    const defaultNames = merge(plainNames, { flat: defaultOptions.names.flat });
-    const names = merge(defaultNames, { flat: option?.name });
-    const opts = merge(defaultOptions, { names });
-    const parser = createParser(opts);
-    const rule = fence_custom(getAllNames(opts), parser);
-    md.block.ruler.before("fence", "csv_table", rule);
+export const flatTable = (md) => {
+    const parser = unifiedParser(defaultOption);
+    const rule = fence_custom(langNames.flat, parser);
+    md.block.ruler.before("fence", "flat_table", rule);
 };
-export const csvTable = (md, option) => {
-    const defaultNames = merge(plainNames, { csv: defaultOptions.names.csv });
-    const names = merge(defaultNames, { csv: option?.name });
-    const opts = merge(defaultOptions, { names });
-    const parser = createParser(opts);
-    const rule = fence_custom(getAllNames(opts), parser);
+export const csvTable = (md) => {
+    const parser = unifiedParser(defaultOption);
+    const rule = fence_custom(langNames.csv, parser);
     md.block.ruler.before("fence", "csv_table", rule);
 };
-export const tsvTable = (md, option) => {
-    const defaultNames = merge(plainNames, { tsv: defaultOptions.names.csv });
-    const names = merge(defaultNames, { tsv: option?.name });
-    const opts = merge(defaultOptions, { names });
-    const parser = createParser(opts);
-    const rule = fence_custom(getAllNames(opts), parser);
-    md.block.ruler.before("fence", "csv_table", rule);
+export const tsvTable = (md) => {
+    const parser = unifiedParser(defaultOption);
+    const rule = fence_custom(langNames.tsv, parser);
+    md.block.ruler.before("fence", "tsv_table", rule);
 };
 export default advTable;

package/lib/table-builder.d.ts

@@ -11,6 +11,7 @@ export declare class TableBuilder implements ITableBuilder {
     readonly tableSpec: TableSpec;
     readonly _cells: CellState;
     constructor(state: StateBlock, tableSpec: TableSpec);
+    static newLocal(state: StateBlock, tableSpec: TableSpec): TableBuilder;
     private get useColgroup();
     private get useTHead();
     private get useTBody();

package/lib/table-builder.js

@@ -9,6 +9,9 @@ export class TableBuilder {
         this.tableSpec = tableSpec;
         this._cells = new CellState(tableSpec);
     }
+    static newLocal(state, tableSpec) {
+        return new TableBuilder(new state.md.block.State("", state.md, state.env, []), tableSpec);
+    }
     get useColgroup() {
         return this.tableSpec.attr.cols?.startsWith("\"");
     }
@@ -23,6 +26,15 @@ export class TableBuilder {
         this.tableSpec.classes.forEach(name => {
             token.attrJoin("class", name);
         });
+        if (this.tableSpec.attr["width"] !== undefined) {
+            const width = this.tableSpec.attr["width"];
+            if (/^\d+$/.test(width)) {
+                token.attrSet("width", width);
+            }
+            else {
+                token.attrSet("style", `width: ${width}`);
+            }
+        }
         if (this.tableSpec.attr["caption"] !== undefined) {
             this.setCaption(this.tableSpec.attr["caption"]);
         }
@@ -86,10 +98,9 @@ export class TableBuilder {
     setColgroup(numCols) {
         this.state.push("colgroup_open", "colgroup", 1);
         for (let c = 0; c < numCols; c++) {
-            const colWidthRatio = this.tableSpec.colspecs.colWidthRatio(c);
-            const colWidth = `${Math.round(colWidthRatio * 100).toFixed(0)}%`;
+            const widthProp = this.tableSpec.colspecs.colWidthPropValue(c);
             const token = this.state.push("col", "col", 0);
-            token.attrSet("style", `width: ${colWidth}`);
+            token.attrSet("style", `width: ${widthProp}`);
         }
         this.state.push("colgroup_close", "colgroup", -1);
     }

package/lib/table.d.ts

@@ -7,7 +7,7 @@ export type TableAttr = {
 };
 export interface ColumnAttr {
     align?: HAlign;
-    width?: string;
+    width?: ColWidth;
 }
 export type CellAttr = {
     align?: HAlign;
@@ -15,6 +15,13 @@ export type CellAttr = {
     rowspan?: number;
     header?: boolean;
 };
+export declare class ColWidth {
+    text: string;
+    constructor(text: string);
+    get hasUnit(): boolean;
+    get relSize(): number;
+    static widthPropertyValue(c: ColWidth, all: ColWidth[]): string;
+}
 export declare class TableSpec {
     readonly attr: TableAttr;
     readonly classes: string[];
@@ -32,8 +39,8 @@ export declare class ColSpecs {
     readonly specs: readonly ColumnAttr[];
     constructor(colspec: string);
     colSpec(col: number): ColumnAttr;
-    colWidth(col: number): number;
-    colWidthRatio(col: number): number;
+    colWidth(col: number): ColWidth;
+    colWidthPropValue(col: number): string;
     lazyInit(cols: number): void;
     static parseColSpec(spec: string): ColumnAttr;
 }

package/lib/table.js

@@ -1,4 +1,43 @@
 import { Lexer, unwrapLiteral } from "./lexer.js";
+const cssUnits = [
+    "px", "%", "em", "rem",
+    "ex", "rex", "cap", "rcap",
+    "cm", "mm", "Q", "in", "pt", "pc",
+    "ch", "rch", "ic", "ric", "lh", "rlh",
+    "vw", "vh", "vi", "vb", "vmin", "vmax",
+    "svw", "svh", "svi", "svb", "svmin", "svmax",
+    "lvw", "lvh", "lvi", "lvb", "lvmin", "lvmax",
+    "dvw", "dvh", "dvi", "dvb", "dvmin", "dvmax",
+    "cqw", "cqh", "cqi", "cqb", "cqmin", "cqmax"
+];
+export class ColWidth {
+    text;
+    constructor(text) {
+        this.text = text;
+    }
+    get hasUnit() {
+        return !/^\d+$/.test(this.text);
+    }
+    get relSize() {
+        return this.hasUnit ? 0 : parseInt(this.text, 10);
+    }
+    static widthPropertyValue(c, all) {
+        if (c.hasUnit) {
+            return c.text;
+        }
+        const total = all
+            .filter(cw => !cw.hasUnit)
+            .reduce((sum, cw) => sum + cw.relSize, 0);
+        const exclude = all.filter(cw => cw.hasUnit);
+        if (exclude.length === 0) {
+            return `calc(100% * ${c.relSize} / ${total})`;
+        }
+        else {
+            const sum = exclude.map(cw => cw.text).join(" + ");
+            return `calc((100% - (${sum})) * ${c.relSize} / ${total})`;
+        }
+    }
+}
 export class TableSpec {
     attr;
     classes;
@@ -16,8 +55,8 @@ export class TableSpec {
         return this.colspecs.numCols;
     }
     static parseClass(classnames) {
-        return classnames
-            .split(",")
+        return unwrapLiteral(classnames, "\"")
+            .split(/[\s,]/)
             .map((s) => s.trim())
             .filter(s => s.length > 0)
             .filter((s, i, arr) => arr.indexOf(s) === i);
@@ -79,6 +118,7 @@ export class TableSpec {
             "header-cols": "",
             "header-rows": "",
             class: "",
+            width: "",
             format: ""
         };
         return Object.keys(k);
@@ -108,16 +148,14 @@ export class ColSpecs {
     colWidth(col) {
         const spec = this.colSpec(col);
         if (spec.width) {
-            return parseInt(spec.width, 10);
+            return spec.width;
         }
-        return 1;
+        return new ColWidth("1");
     }
-    colWidthRatio(col) {
-        let totalWidth = 0;
-        for (let c = 0; c < this.numCols; c++) {
-            totalWidth += this.colWidth(c);
-        }
-        return this.colWidth(col) / totalWidth;
+    colWidthPropValue(col) {
+        const c = this.colWidth(col);
+        const all = this.specs.map(s => s.width || new ColWidth("1"));
+        return ColWidth.widthPropertyValue(c, all);
     }
     lazyInit(cols) {
         this.numCols = cols;
@@ -141,7 +179,7 @@ export class ColSpecs {
                 attr.align = "right";
             }
             else if (char >= "0" && char <= "9") {
-                attr.width = consumeNumber();
+                attr.width = consumeColWidth();
                 break;
             }
             else {
@@ -152,11 +190,13 @@ export class ColSpecs {
         function consume() {
             return spec[pos++];
         }
-        function consumeNumber() {
-            const match = spec.slice(pos).match(/^\d+/);
+        function consumeColWidth() {
+            const regex = new RegExp(`^\\d+(${cssUnits.join("|")})?`);
+            const match = spec.slice(pos).match(regex);
             if (!match)
-                throw new Error("cannot consume number");
-            return match[0];
+                throw new Error("cannot consume col width");
+            pos += match[0].length;
+            return new ColWidth(match[0]);
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdown-it-adv-table",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Markdown syntax extension for better table support",
   "keywords": [
     "markdown",
@@ -34,13 +34,13 @@
     "lint:fix": "eslint src --fix"
   },
   "devDependencies": {
-    "@cobapen/eslint-config": "^0.4.0",
+    "@cobapen/eslint-config": "^0.5.0",
     "@types/markdown-it": "^14.1.2",
-    "@types/node": "^22.14.1",
-    "@vitest/coverage-v8": "^3.1.1",
-    "eslint": "^9.24.0",
+    "@types/node": "^25.2.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.39.2",
     "markdown-it": "^14.1.0",
-    "typescript": "^5.8.3",
-    "vitest": "^3.1.1"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   }
 }