markdown-it-ltem 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EurekaAI Co., Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# markdown-it-ltem
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[markdown-it](https://github.com/markdown-it/markdown-it) plugin for [LTEM](../../../../README.md) tables: Markdown pipe tables with merged cells and multi-row headers.
+
+```
+| Region | Revenue | <<  |
+| ^^     | Q1      | Q2  |
+|--------|---------|-----|
+| Asia   | 100     | 120 |
+```
+
+renders as a table whose "Region" cell spans two rows and whose "Revenue" cell spans two columns.
+
+Status: version 0.1.0, the first release, for LTEM 1.0. Not yet published to npm. The API may change before version 1.0.0.
+
+## Install
+
+```
+npm install markdown-it markdown-it-ltem
+```
+
+Works with markdown-it 14 and 15. The package is ESM; CommonJS code can use `require("markdown-it-ltem").default` on Node.js 20.19, 22.12 or later.
+
+## Use
+
+```ts
+import markdownit from "markdown-it";
+import ltem from "markdown-it-ltem";
+
+const md = markdownit().use(ltem);
+md.render(text);
+```
+
+The plugin replaces markdown-it's GFM table rule and enables it, also in presets that have no table rule (such as `commonmark` and `zero`). A table without LTEM notation renders as before. LTEM tables get `colspan`, `rowspan` and several header rows, following the LTEM specification, version 1.0:
+
+- Header rows are the line directly above the delimiter row and the pipe-led lines above it. A `| # identifier |` line is reserved and stays in the paragraph before the table. A table may begin on any line of a paragraph; a delimiter row whose last header row does not fit stays ordinary text. A line such as `- | -` is a list item, not a delimiter row, as in GFM.
+- Body rows end at a blank line, a line indented by four or more spaces, or a line that starts another block (block quote, ATX heading, fenced code, thematic break, list item), and also wherever markdown-it's own rules start a block, such as an HTML block.
+- `\\` in a cell is a line break. Each line is parsed as inlines on its own and the lines are joined with hard breaks (`<br>`).
+- Alignment from the delimiter row is written as `style="text-align:..."`, as markdown-it does.
+
+The token stream is the one markdown-it's table rule produces: `table_open`, `thead_open`, `tr_open`, `th_open` or `td_open` (with `colspan` and `rowspan` attributes when greater than 1), one `inline` token per cell, and the matching close tokens. There is no `tbody` when the table has no body rows.
+
+Each `th_open` and `td_open` token has `map = [line, line + 1]` (the document line of the cell's origin) and `meta.ltem = { row, col, rowspan, colspan, line, start, end }`: the cell's grid position and where its source is. `start` and `end` are UTF-16 offsets (JavaScript string indices) in that document line, counted from the line's first character, so a container prefix such as `> ` shifts them; they cover the cell's source without the spaces and tabs around it, including any span attribute and escapes. Editors can use them to map a rendered cell back to the text.
+
+## Development
+
+See the [workspace README](../../README.md). The tests render all specification examples as whole documents with markdown-it 14 and 15.

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * markdown-it plugin for LTEM tables.
+ *
+ * ```ts
+ * import markdownit from "markdown-it";
+ * import ltem from "markdown-it-ltem";
+ *
+ * const md = markdownit("commonmark").use(ltem);
+ * const html = md.render(text);
+ * ```
+ *
+ * The plugin replaces markdown-it's GFM table rule. A table without LTEM notation
+ * renders as before; LTEM tables get colspan, rowspan and several header rows.
+ *
+ * @packageDocumentation
+ */
+interface Ruler {
+    at(name: string, fn: never, options?: {
+        alt?: string[];
+    }): void;
+    before(beforeName: string, ruleName: string, fn: never, options?: {
+        alt?: string[];
+    }): void;
+    after(afterName: string, ruleName: string, fn: never, options?: {
+        alt?: string[];
+    }): void;
+    enable(list: string | string[], ignoreInvalid?: boolean): string[];
+}
+/**
+ * Where a cell is in the document, set as `meta.ltem` on its `th_open` or `td_open`
+ * token. `line` is the document line of the cell's origin (counting from 0, like token
+ * maps). `start` and `end` are UTF-16 offsets (JavaScript string indices) in that line of
+ * markdown-it's source, counted from the line's first character, so a container prefix
+ * such as "> " shifts them. They cover the cell's source without the spaces and tabs
+ * around it, including any span attribute and escapes; an empty cell has start == end.
+ */
+export interface LtemCellPosition {
+    row: number;
+    col: number;
+    rowspan: number;
+    colspan: number;
+    line: number;
+    start: number;
+    end: number;
+}
+/** The parts of a markdown-it instance that the plugin uses. */
+export interface MarkdownItLike {
+    block: {
+        ruler: Ruler;
+    };
+    core: {
+        ruler: Ruler;
+    };
+}
+/** Replace the table rule of `md` with the LTEM table rule and enable it. */
+export default function ltem(md: MarkdownItLike): void;
+export { ltem };

package/dist/index.js

@@ -0,0 +1,237 @@
+/**
+ * markdown-it plugin for LTEM tables.
+ *
+ * ```ts
+ * import markdownit from "markdown-it";
+ * import ltem from "markdown-it-ltem";
+ *
+ * const md = markdownit("commonmark").use(ltem);
+ * const html = md.render(text);
+ * ```
+ *
+ * The plugin replaces markdown-it's GFM table rule. A table without LTEM notation
+ * renders as before; LTEM tables get colspan, rowspan and several header rows.
+ *
+ * @packageDocumentation
+ */
+import { endsTableBody, isDelimiterRow, isUpperHeaderRow, parseTable, startsBlock, } from "ltem-core";
+const ALT = ["paragraph", "reference"];
+/** Replace the table rule of `md` with the LTEM table rule and enable it. */
+export default function ltem(md) {
+    const rule = ltemTable;
+    try {
+        md.block.ruler.at("table", rule, { alt: ALT });
+    }
+    catch {
+        // The preset has no table rule; tables are tried before indented code, as in markdown-it.
+        md.block.ruler.before("code", "table", rule, { alt: ALT });
+    }
+    md.block.ruler.enable("table");
+    md.core.ruler.before("inline", "ltem_split_lines", splitCellLines);
+    md.core.ruler.after("inline", "ltem_join_lines", joinCellLines);
+}
+export { ltem };
+// -- the block rule --------------------------------------------------------------------
+/** Line n as the LTEM core reads it: indentation relative to the block, then the text. */
+function lineText(state, n) {
+    const indent = Math.max(0, state.sCount[n] - state.blkIndent);
+    return " ".repeat(indent) + state.src.slice(state.bMarks[n] + state.tShift[n], state.eMarks[n]);
+}
+/** Whether line n can belong to a table: not blank and inside the current container. */
+function usable(state, n, endLine) {
+    return n < endLine && !state.isEmpty(n) && state.sCount[n] >= state.blkIndent;
+}
+function isCodeIndented(state, n) {
+    return state.sCount[n] - state.blkIndent >= 4;
+}
+/** Index of the first delimiter row if a table's header rows start at `start` (spec 2.3), else -1. */
+function findDelimiter(state, start, endLine) {
+    for (let n = start; usable(state, n, endLine) && usable(state, n + 1, endLine); n++) {
+        // Line n is the last header row: a paragraph line, as in GFM (spec 2.3), so not the start
+        // of another block. isDelimiterRow rejects a delimiter row indented as code.
+        if (isDelimiterRow(lineText(state, n + 1)))
+            return startsBlock(lineText(state, n)) ? -1 : n + 1;
+        // Header rows above the last one begin with a pipe, are not reserved and do not look
+        // like a delimiter row (spec 2.3, 9).
+        if (!isUpperHeaderRow(lineText(state, n)))
+            return -1;
+    }
+    return -1;
+}
+/** Whether a body row ends before line n (spec 2.4), by the core's rules or markdown-it's. */
+function endsBody(state, n, endLine, terminators) {
+    if (!usable(state, n, endLine) || isCodeIndented(state, n))
+        return true;
+    if (endsTableBody(lineText(state, n)))
+        return true;
+    return terminators.some((rule) => rule(state, n, endLine, true));
+}
+function ltemTable(state, startLine, endLine, silent) {
+    if (isCodeIndented(state, startLine))
+        return false;
+    // Called to end a paragraph at startLine: if the line above is a pipe-led line of the
+    // same paragraph, it would be a header row of any table here, so no table starts at
+    // startLine (spec 2.3). Not so if startLine looks like a delimiter row: as a last
+    // header row it stands alone.
+    if (silent && startLine > 0 && isUpperHeaderRow(lineText(state, startLine - 1))
+        && !isDelimiterRow(lineText(state, startLine)))
+        return false;
+    const delimiter = findDelimiter(state, startLine, endLine);
+    if (delimiter < 0)
+        return false;
+    let stop = delimiter + 1;
+    if (!silent) {
+        // Body rows run until a blank line or a line that starts another block.
+        const terminators = state.md.block.ruler.getRules("blockquote");
+        const oldParentType = state.parentType;
+        state.parentType = "table";
+        while (!endsBody(state, stop, endLine, terminators))
+            stop++;
+        state.parentType = oldParentType;
+    }
+    const lines = [];
+    for (let n = startLine; n < stop; n++)
+        lines.push(lineText(state, n));
+    const result = parseTable(lines);
+    // No table here, for example if the last header row does not fit (spec 2.3).
+    if (result.table === null || result.start !== 0 || result.end !== lines.length)
+        return false;
+    if (silent)
+        return true;
+    emitTable(state, result.table, result.sources, startLine, delimiter, stop);
+    state.line = stop;
+    return true;
+}
+// -- tokens ----------------------------------------------------------------------------
+/** The lines of each cell's inline token whose text has more than one line (spec 4.2). */
+const cellLines = new WeakMap();
+/** The cell token that each per-line inline token belongs to, while inlines are parsed. */
+const lineOwner = new WeakMap();
+/**
+ * The offset in document line n of markdown-it's source for offset i of `lineText(n)`,
+ * which replaces the container prefix and indentation by spaces.
+ */
+function documentOffset(state, n, i) {
+    const lineStart = state.src.lastIndexOf("\n", state.bMarks[n] - 1) + 1;
+    const indent = Math.max(0, state.sCount[n] - state.blkIndent);
+    const textStart = state.bMarks[n] + state.tShift[n];
+    return textStart + Math.max(0, i - indent) - lineStart;
+}
+function emitTable(state, table, sources, start, delimiter, stop) {
+    const byRow = new Map(); // indices into table.cells and sources
+    table.cells.forEach((cell, i) => {
+        const row = byRow.get(cell.row);
+        if (row)
+            row.push(i);
+        else
+            byRow.set(cell.row, [i]);
+    });
+    // Source line of each grid row: header rows, then (after the delimiter) body rows.
+    const sourceLine = (r) => (r < table.header_rows ? start + r : start + r + 1);
+    const emitRow = (r) => {
+        const tag = r < table.header_rows ? "th" : "td";
+        const line = sourceLine(r);
+        state.push("tr_open", "tr", 1).map = [line, line + 1];
+        for (const i of byRow.get(r) ?? []) {
+            const cell = table.cells[i];
+            const source = sources[i];
+            const open = state.push(`${tag}_open`, tag, 1);
+            open.map = [line, line + 1];
+            const position = {
+                row: cell.row, col: cell.col, rowspan: cell.rowspan, colspan: cell.colspan, line,
+                start: documentOffset(state, start + source.line, source.start),
+                end: documentOffset(state, start + source.line, source.end),
+            };
+            open.meta = { ltem: position };
+            const attrs = [];
+            if (cell.colspan > 1)
+                attrs.push(["colspan", String(cell.colspan)]);
+            if (cell.rowspan > 1)
+                attrs.push(["rowspan", String(cell.rowspan)]);
+            const align = table.align[cell.col];
+            if (align)
+                attrs.push(["style", `text-align:${align}`]);
+            if (attrs.length)
+                open.attrs = attrs;
+            const lines = cell.text.split("\n");
+            const inline = state.push("inline", "", 0);
+            // A backslash before a line end is a hard break (spec 4.2: lines join with <br />).
+            inline.content = lines.join("\\\n");
+            inline.map = [line, line + 1];
+            inline.children = [];
+            if (lines.length > 1)
+                cellLines.set(inline, lines);
+            state.push(`${tag}_close`, tag, -1);
+        }
+        state.push("tr_close", "tr", -1);
+    };
+    state.push("table_open", "table", 1).map = [start, stop];
+    state.push("thead_open", "thead", 1).map = [start, delimiter];
+    for (let r = 0; r < table.header_rows; r++)
+        emitRow(r);
+    state.push("thead_close", "thead", -1);
+    if (table.rows > table.header_rows) {
+        state.push("tbody_open", "tbody", 1).map = [delimiter + 1, stop];
+        for (let r = table.header_rows; r < table.rows; r++)
+            emitRow(r);
+        state.push("tbody_close", "tbody", -1);
+    }
+    state.push("table_close", "table", -1);
+}
+// -- line breaks in cells (spec 4.2) -----------------------------------------------------
+//
+// Each line of a cell is parsed as inlines on its own, so that emphasis or a code span
+// cannot run across a `\\` line break. Just before markdown-it's "inline" core rule, a
+// cell's inline token is replaced by one inline token per line; just after it, the
+// lines' children are joined back into the cell's token with hard breaks between them.
+// Every other core rule sees one inline token per cell.
+function replaceTokens(state, map) {
+    const out = [];
+    for (const token of state.tokens)
+        map(token, out);
+    state.tokens.length = 0;
+    for (const token of out)
+        state.tokens.push(token);
+}
+function splitCellLines(state) {
+    if (!state.tokens.some((token) => cellLines.has(token)))
+        return;
+    replaceTokens(state, (token, out) => {
+        const lines = cellLines.get(token);
+        if (!lines) {
+            out.push(token);
+            return;
+        }
+        for (const line of lines) {
+            const part = new state.Token("inline", "", 0);
+            part.content = line;
+            part.map = token.map;
+            part.level = token.level;
+            part.children = [];
+            lineOwner.set(part, token);
+            out.push(part);
+        }
+    });
+}
+function joinCellLines(state) {
+    if (!state.tokens.some((token) => lineOwner.has(token)))
+        return;
+    replaceTokens(state, (token, out) => {
+        const owner = lineOwner.get(token);
+        if (!owner) {
+            out.push(token);
+            return;
+        }
+        const children = owner.children ?? [];
+        if (out[out.length - 1] === owner) {
+            children.push(new state.Token("hardbreak", "br", 0));
+        }
+        else {
+            children.length = 0;
+            out.push(owner);
+        }
+        for (const child of token.children ?? [])
+            children.push(child);
+        owner.children = children;
+    });
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "markdown-it-ltem",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "markdown-it plugin for LTEM tables: merged cells (colspan, rowspan) and multi-row headers",
+  "license": "MIT",
+  "keywords": [
+    "markdown-it-plugin",
+    "markdown-it",
+    "markdown",
+    "table",
+    "colspan",
+    "rowspan",
+    "ltem"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.test.json && node --test \"test/**/*.test.ts\"",
+    "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\""
+  },
+  "dependencies": {
+    "ltem-core": "0.1.0"
+  },
+  "peerDependencies": {
+    "markdown-it": "^14 || ^15"
+  },
+  "devDependencies": {
+    "markdown-it": "^15.0.2",
+    "markdown-it-14": "npm:markdown-it@^14.3.2"
+  }
+}