Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 89 additions & 0 deletions e2e/math-svelte.e2e.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
import { expect, test } from "@playwright/test";
import { parseMarkdown } from "comark";
import math from "../packages/math/src/index.ts";
import { svelteBundle } from "../packages/math/test/svelte-bundle.ts";

const MATHML = "http://www.w3.org/1998/Math/MathML";
const markdown = "Mass $\\frac{a}{b}$, and a broken $\\frac{a}$.\n\n$$\n\\sum_i i\n$$\n";

let bundle: string;
test.beforeAll(async () => {
bundle = await svelteBundle("./fixtures/svelte-client.ts", "client");
});

// @comark/svelte creates elements in the browser with <svelte:element>, which gives MathML's tags the HTML
// namespace; a server render doesn't show it, since the page's parser makes them MathML.
test("@comark/svelte gives formulas made in the browser MathML's namespace", async ({ page }) => {
const value = await parseMarkdown(markdown, { plugins: [math()] });
await page.setContent("<!doctype html><meta charset=utf-8><body></body>");
await page.addScriptTag({ content: bundle });
// The document goes as JSON, the form a page receives it in.
await page.evaluate((json) => {
const app = window as unknown as {
fixture: { mountDocument: (document: unknown) => (next: unknown) => void };
update: (next: unknown) => void;
};
app.update = app.fixture.mountDocument(JSON.parse(json));
}, JSON.stringify(value));
await expect(page.locator(".cmh")).toHaveCount(3);
const shown = await page.evaluate(() =>
[...document.querySelectorAll(".cmh")].map((formula) => {
const visible = [...formula.querySelectorAll("math")].filter(
(math) => math.getBoundingClientRect().width > 0,
);
return {
source: formula.classList.contains("cmh-source") ? formula.textContent : null,
namespaces: visible.map((math) => [
math.namespaceURI,
math.querySelector("mi, mn, mo")?.namespaceURI,
]),
};
}),
);
expect(shown).toEqual([
{ source: null, namespaces: [[MATHML, MATHML]] },
{ source: "\\frac{a}", namespaces: [] },
{ source: null, namespaces: [[MATHML, MATHML]] },
]);

// A formula that didn't typeset becomes one that does, in the same component, as while someone fixes their TeX.
const fixed = await parseMarkdown(markdown.replace("\\frac{a}$", "\\frac{a}{c}$"), {
plugins: [math()],
});
await page.evaluate(
(json) => (window as unknown as { update: (next: unknown) => void }).update(JSON.parse(json)),
JSON.stringify(fixed),
);
await expect(page.locator(".cmh-source")).toHaveCount(0);
const updated = await page.evaluate(() =>
[...document.querySelectorAll(".cmh")].map(
(formula) =>
[...formula.querySelectorAll("math")].find((math) => math.getBoundingClientRect().width > 0)
?.namespaceURI,
),
);
expect(updated).toEqual([MATHML, MATHML, MATHML]);

// A formula that goes to TeX and comes back shows its new MathML, not the copy of the one before.
const update = (source: string) =>
parseMarkdown(source, { plugins: [math()] }).then((next) =>
page.evaluate(
(json) =>
(window as unknown as { update: (next: unknown) => void }).update(JSON.parse(json)),
JSON.stringify(next),
),
);
await update("$a$");
await update("$\\frac{a}$");
await expect(page.locator(".cmh-source")).toHaveCount(1);
await update("$b$");
await expect(page.locator(".cmh")).toHaveCount(1);
const last = await page
.locator(".cmh")
.evaluate((formula) =>
[...formula.querySelectorAll("math")]
.filter((math) => math.getBoundingClientRect().width > 0)
.map((math) => [math.namespaceURI, math.querySelector("mi")?.textContent]),
);
expect(last).toEqual([[MATHML, "b"]]);
});
14 changes: 9 additions & 5 deletions packages/lint/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -489,11 +489,15 @@ function unknownComponents(
...new Set((Array.isArray(components) ? components : Object.keys(components)).map(kebab)),
].sort();
const known = new Set([...names, ...htmlTags]);
const used: { name: string; written: string; line: number; column?: number }[] = blocks.map(
(block) => ({
...block,
written: `${source.lines[block.line - 1]?.trim().match(/^:+/)?.[0] ?? "::"}${block.name}`,
}),
// A plugin can turn its own syntax into a block while parsing, as comark-mathml does with `$$`, under a name the
// document never writes. Only a block whose line writes `:name`, in any case Comark reads, is the author's.
const used: { name: string; written: string; line: number; column?: number }[] = blocks.flatMap(
(block) => {
const text = source.lines[block.line - 1] ?? "";
const written = [...text.matchAll(/:([A-Za-z][\w-]*)/g)].map(([, name = ""]) => kebab(name));
if (!written.includes(kebab(block.name))) return [];
return [{ ...block, written: `${text.trim().match(/^:+/)?.[0] ?? "::"}${block.name}` }];
},
);
let range: [number, number] | null = null;
for (const token of tokens) {
Expand Down
2 changes: 1 addition & 1 deletion packages/lint/src/rules/math.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,6 @@ export default {
},
"comark/math/authored-html": {
code: "COMARK4103",
title: "Write math between `$` signs, not as a formula's `html`",
title: "Write math between `$` signs, not as a `formula` element",
},
} satisfies Record<`comark/math/${string}`, RuleInfo>;
16 changes: 16 additions & 0 deletions packages/lint/test/lint.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,22 @@ describe("comark/unknown-component", () => {
]);
});

it("leaves out the blocks a plugin makes from its own syntax, such as display math", async () => {
const { default: math, components: mathComponents } = await import("comark-mathml/html");
const markdown =
"Mass $E = mc^2$.\n\n$$\n\\frac{a}{b}\n$$\n\n```math\n\\sum_i i\n```\n\n::mystery\n::";
const found = await lint(markdown, {
plugins: [math()],
components: [...Object.keys(mathComponents), "screenshot"],
});
expect(found.map(({ rule, line }) => [rule, line])).toEqual([["comark/unknown-component", 11]]);
const cased = await lint("::Screnshot\n::\n\n:Screnshot[x]\n\n::UnknownThing\n::", {
plugins: [math()],
components: ["Screenshot"],
});
expect(cased.map(({ line }) => line)).toEqual([1, 4, 6]);
});

it("is off without components, since any name could be valid", async () => {
expect(await lint("::anything\n::")).toEqual([]);
});
Expand Down
12 changes: 12 additions & 0 deletions packages/math/docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,18 @@ import math, { components } from "comark-mathml/html";
const render = createHtmlRenderer({ plugins: [math()], components });
```

With Comark's `security` plugin, allow `formula` and the MathML elements the package exports as `MATHML_TAGS`, and `KATEX_TAGS` too for KaTeX's HTML. `comarkUi()` already lists them in its `tags`.

```ts
import security from "comark/plugins/security";
import math, { components, MATHML_TAGS } from "comark-mathml/html";

const render = createHtmlRenderer({
plugins: [math(), security({ allowedTags: ["p", "formula", ...MATHML_TAGS] })],
components,
});
```

For Vue, React, or Svelte, import from `comark-mathml/vue`, `comark-mathml/react`, or `comark-mathml/svelte`. The components add the styles on mount. On a server-rendered page, also import `comark-mathml/style.css` so it doesn't shift. [Renderers](/guide/renderers) covers using it with other plugins.

## Theme
Expand Down
1 change: 1 addition & 0 deletions packages/math/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@
"devDependencies": {
"@comark/html": "catalog:",
"@comark/react": "catalog:",
"@comark/svelte": "catalog:",
"@comark/vue": "catalog:",
"@types/react": "catalog:",
"@types/react-dom": "catalog:",
Expand Down
37 changes: 30 additions & 7 deletions packages/math/src/html.ts
Original file line number Diff line number Diff line change
@@ -1,21 +1,44 @@
import type { NodeHandler } from "comark";
import { escapeHtml } from "comark/utils";
import type { Node, NodeHandler } from "comark";
import { classOf } from "./client.ts";
import { css } from "./styles.ts";
import { isElement } from "../../../shared/nodes.ts";
import { rawText } from "../../../shared/text.ts";

export { default } from "./index.ts";
export { default, KATEX_TAGS, MATHML_TAGS } from "./index.ts";
export type { FormulaAttributes, MathMeta, MathOptions, MathOutput } from "./index.ts";

// The nodes hold decoded text, so every `&` is escaped, including one that looks like an entity, as `&lt;` in
// `\verb|&lt;|` does. Comark's `escapeHtml` leaves those as they are.
const escape = (text: string) =>
text.replace(/[&<>"]/g, (char) => `&${{ "&": "amp", "<": "lt", ">": "gt", '"': "quot" }[char]};`);

/**
* A formula's MathML as markup, with no whitespace added: Comark's renderer indents elements it doesn't know, which
* would pad each `<mi>` and the TeX that copying reads.
*/
const markup = (nodes: Node[]): string =>
nodes
.map((node) => {
if (!Array.isArray(node)) return escape(node);
if (!isElement(node)) return "";
const [tag, attrs, ...children] = node;
const attributes = Object.entries(attrs)
.filter(([name, value]) => name !== "$" && value !== undefined && value !== null)
.map(([name, value]) => ` ${name}="${escape(String(value))}"`)
.join("");
return `<${tag}${attributes}>${markup(children)}</${tag}>`;
})
.join("");

// Each render gets a fresh `state.context`, so a document carries the styles once.
const styled = new WeakSet<object>();

const formula: NodeHandler = ([, attrs], state) => {
const html = rawText(attrs.html);
const formula: NodeHandler = ([, attrs, ...children], state) => {
const styles = styled.has(state.context) ? "" : `<style data-comark-mathml>${css}</style>`;
styled.add(state.context);
// The plugin typeset `html` itself, with links and other trusted commands off.
return `${styles}<span class="${classOf(attrs.display === true, !!html)}">${html || escapeHtml(rawText(attrs.tex))}</span>`;
const typeset = children.length > 0;
const body = typeset ? markup(children) : escape(rawText(attrs.tex));
return `${styles}<span class="${classOf(attrs.display === true, typeset)}">${body}</span>`;
};

/** The HTML renderer for math. Pass it as `components`; it inlines the styles once per document. */
Expand Down
33 changes: 21 additions & 12 deletions packages/math/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,12 @@ import {
type StateInline,
type Token,
} from "../../../shared/markdown-it.ts";
import { markupToNodes } from "./markup.ts";
import { type MathOutput, typesetter } from "./typeset.ts";
import { isElement } from "../../../shared/nodes.ts";

export type { MathOutput } from "./typeset.ts";
export { KATEX_TAGS, MATHML_TAGS } from "./markup.ts";

export interface MathOptions {
/**
Expand All @@ -33,10 +35,11 @@ export type MathMeta = {
type Issue = { rule: `comark/math/${string}`; message: string };

/**
* What a formula becomes, and all its renderers read: its `tex`, `display` for display math, and `html`, the typeset
* markup. A formula with no `html` couldn't be typeset, and renders its TeX.
* What a formula becomes, and all its renderers read: its `tex`, `display` for display math, and `typeset` when its
* children are its MathML, as elements, so a host's `security` plugin checks them like the rest of the document. A
* formula that couldn't be typeset has no children, and renders its TeX.
*/
export type FormulaAttributes = { tex?: string; display?: boolean; html?: string };
export type FormulaAttributes = { tex?: string; display?: boolean; typeset?: boolean };

const DOLLAR = 0x24;
const BACKSLASH = 0x5c;
Expand Down Expand Up @@ -208,13 +211,17 @@ export default defineComarkPlugin<MathOptions | undefined, MathMeta>((options =
const node = nodes[index];
if (!node || !isElement(node)) continue;
const [tag, attrs] = node;
// The renderers print `html` as it is, so only markup this plugin typeset may reach them.
if (tag === "formula" && "html" in attrs) {
// A formula's children are MathML that the renderers print as it is, so only formulas this plugin typeset
// may have any. A document that writes a `formula` with content, or the `html` it once carried, hears so.
if (tag === "formula" && ("html" in attrs || "typeset" in attrs || node.length > 2)) {
delete attrs.html;
delete attrs.typeset;
node.length = 2;
issues.push({
rule: "comark/math/authored-html",
message: `A \`formula\` element sets \`html\`, which only comark-mathml writes, so it's ignored. Write the formula between \`$\` signs instead.`,
message: `A \`formula\` element has content of its own, which only comark-mathml writes, so it's ignored. Write the formula between \`$\` signs instead.`,
});
continue;
}
const inHtml = html || !!attrs.$?.html;
if (!inHtml && tag === source.tag) {
Expand All @@ -238,12 +245,14 @@ export default defineComarkPlugin<MathOptions | undefined, MathMeta>((options =
for (const { list, index, tex, display } of found) {
const result = typeset(tex, display);
const attrs: FormulaAttributes = display ? { tex, display } : { tex };
if ("html" in result) attrs.html = result.html;
else
issues.push({
rule: "comark/math/invalid-tex",
message: `Math \`${quoted(tex)}\` failed to typeset: ${result.reason}. Fix the TeX or wrap it in code.`,
});
if ("html" in result) {
list[index] = ["formula", { ...attrs, typeset: true }, ...markupToNodes(result.html)];
continue;
}
issues.push({
rule: "comark/math/invalid-tex",
message: `Math \`${quoted(tex)}\` failed to typeset: ${result.reason}. Fix the TeX or wrap it in code.`,
});
list[index] = ["formula", attrs];
}
if (!issues.length) return;
Expand Down
60 changes: 60 additions & 0 deletions packages/math/src/markup.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
import type { Node } from "comark";

/** The elements Temml writes, so a host's `security` allowlist keeps a formula's MathML: `a` is a `\ref`. */
export const MATHML_TAGS = (
"a annotation math menclose merror mfrac mglyph mi mmultiscripts mn mo mover mpadded mphantom mprescripts mroot mrow ms " +
"mspace msqrt mstyle msub msubsup msup mtable mtd mtext mtr munder munderover none semantics"
).split(" ");
/** The elements KaTeX's `"html"` and `"htmlAndMathml"` output add to MathML's: its boxes, and its SVG for stretchy marks. */
export const KATEX_TAGS = "line path span svg".split(" ");

const ENTITIES = new Map([
["amp", "&"],
["lt", "<"],
["gt", ">"],
["quot", '"'],
["apos", "'"],
]);
const decode = (text: string) =>
text.replace(/&(#x[\da-f]+|#\d+|\w+);/gi, (entity, name: string) => {
if (name[0] !== "#") return ENTITIES.get(name) ?? entity;
const code =
name[1] === "x" || name[1] === "X" ? parseInt(name.slice(2), 16) : Number(name.slice(1));
return String.fromCodePoint(code);
});

const TOKEN = /<\/([\w:-]+)\s*>|<([\w:-]+)((?:\s+[\w:-]+=(?:"[^"]*"|'[^']*'))*)\s*(\/?)>|([^<]+)/g;
const ATTRIBUTE = /([\w:-]+)=(?:"([^"]*)"|'([^']*)')/g;

/**
* The typesetter's markup as Comark nodes, so a formula reaches the renderers as elements a host's `security` plugin
* checks one by one, rather than as a string of HTML they would have to trust. Temml and KaTeX write well-formed
* markup with quoted attributes and escaped text, which is all this reads.
*/
export function markupToNodes(markup: string): Node[] {
type Frame = { tag: string; attrs: Record<string, string>; children: Node[] };
const root: Node[] = [];
const open: Frame[] = [];
const childrenOf = () => open.at(-1)?.children ?? root;
const close = (tag?: string) => {
if (tag !== undefined && open.at(-1)?.tag !== tag) return;
const frame = open.pop();
if (frame) childrenOf().push([frame.tag, frame.attrs, ...frame.children]);
};
for (const [, closing, tag, attributes = "", selfClosing, text] of markup.matchAll(TOKEN)) {
if (text !== undefined) childrenOf().push(decode(text));
else if (closing) close(closing);
else if (tag) {
const attrs = Object.fromEntries(
[...attributes.matchAll(ATTRIBUTE)].map(([, name = "", double, single]) => [
name,
decode(double ?? single ?? ""),
]),
);
if (selfClosing) childrenOf().push([tag, attrs]);
else open.push({ tag, attrs, children: [] });
}
}
while (open.length) close();
return root;
}
16 changes: 6 additions & 10 deletions packages/math/src/react.ts
Original file line number Diff line number Diff line change
@@ -1,19 +1,15 @@
import { createElement, useEffect } from "react";
import { Children, createElement, type ReactNode, useEffect } from "react";
import { addStyles, classOf } from "./client.ts";
import type { FormulaAttributes } from "./index.ts";

export { default } from "./index.ts";
export { default, KATEX_TAGS, MATHML_TAGS } from "./index.ts";
export type { FormulaAttributes, MathMeta, MathOptions, MathOutput } from "./index.ts";

/** Math for `@comark/react`. */
export function Formula({ tex, display, html }: FormulaAttributes) {
/** Math for `@comark/react`. The typeset MathML arrives as its children. */
export function Formula({ tex, display, children }: FormulaAttributes & { children?: ReactNode }) {
useEffect(addStyles, []);
return html
? // The plugin typeset `html` itself, with links and other trusted commands off.
createElement("span", {
className: classOf(display, true),
dangerouslySetInnerHTML: { __html: html },
})
return Children.count(children)
? createElement("span", { className: classOf(display, true) }, children)
: createElement("span", { className: classOf(display, false) }, tex ?? "");
}

Expand Down
Loading
Loading