rapier-math 1.0.1 → 1.1.0

package/examples/markdown.mjs

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: MIT
+import MarkdownIt from 'markdown-it';
+import rapierMath from 'rapier-math/markdown-it';
+
+export const md = new MarkdownIt({html: false}).use(rapierMath);
+const source = 'It costs $5 and $10. Code: `$$x$$`. Math: \\(x^2\\).\n\n$$\\frac{1}{2}$$\n';
+const env = {};
+console.log(md.render(source, env));
+console.error(env.rapierMathErrors || []);

package/examples/react.tsx

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: MIT
+import {useEffect, useMemo, useRef} from 'react';
+import {render, observe} from 'rapier-math';
+
+export function Equation({source, displayMode = false}: {source: string; displayMode?: boolean}) {
+  const ref = useRef<HTMLSpanElement>(null);
+  const result = useMemo(() => {
+    try { return render(source, {displayMode}); }
+    catch { return null; }
+  }, [source, displayMode]);
+  const svg = result && result.errors.length === 0 ? result.svg : null;
+  useEffect(() => {
+    if (ref.current && svg) return observe(ref.current);
+  }, [svg]); // Cleanup runs before replacement setup and on unmount.
+  if (!svg) return <code>{source}</code>;
+  // The server and initial client render use identical source/options. Fit only
+  // after hydration; never pass authored HTML to dangerouslySetInnerHTML.
+  return <span ref={ref} dangerouslySetInnerHTML={{__html: svg}} />;
+}

package/examples/stream.mjs

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: MIT
+import MarkdownIt from 'markdown-it';
+import rapierMath from 'rapier-math/markdown-it';
+import {createMarkdownStream} from 'rapier-math/stream';
+
+const md = new MarkdownIt({html: false}).use(rapierMath);
+const stream = createMarkdownStream(source => md.render(source, {}), {previewEvery: 16});
+for (const chunk of ['The answer is \\(', '\\frac{1}', '{2}', '\\)', '. Code: `$$x$$`.']) {
+  const preview = stream.write(chunk);
+  if (preview) console.log({phase: 'preview', ...preview});
+}
+const final = stream.finish();
+console.log({phase: 'complete', ...final});
+if (final.html !== md.render(final.source, {})) throw new Error('Batch mismatch');
+
+// One stream per message. On replacement: cancel its transport, reset, write.
+stream.reset();
+stream.write('Replacement \\(y\\).');
+console.log(stream.finish());

package/examples/unified.mjs

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: MIT
+import {unified} from 'unified';
+import remarkParse from 'remark-parse';
+import remarkMath from 'remark-math';
+import remarkRehype from 'remark-rehype';
+import rehypeSanitize, {defaultSchema} from 'rehype-sanitize';
+import rehypeRapierMath from 'rapier-math/rehype';
+import rehypeStringify from 'rehype-stringify';
+import {pathToFileURL} from 'node:url';
+
+export const processor = unified().use(remarkParse)
+  .use(remarkMath, {singleDollarTextMath: false}).use(remarkRehype)
+  .use(rehypeSanitize, {
+    ...defaultSchema,
+    attributes: {...defaultSchema.attributes, code: [
+      ...(defaultSchema.attributes.code || []).filter(rule => !(Array.isArray(rule) && rule[0] === 'className')),
+      ['className', 'language-math', 'math-inline', 'math-display'],
+    ]},
+  })
+  .use(rehypeRapierMath).use(rehypeStringify);
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const file = await processor.process('Price $5. Code `$$x$$`. Math $$x^2$$.\n\n$$\n\\frac{1}{2}\n$$');
+  console.log(String(file));
+  console.error(file.messages);
+}

package/examples/worker.mjs

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT
+import {render} from '../index.mjs';
+self.onmessage = ({data: {id, source}}) => {
+  try { self.postMessage({id, source, result: render(source)}); }
+  catch (error) { self.postMessage({id, source, error: {code: error.code, message: error.message}}); }
+};
+// Keep a request id per message; install a reply only if it is still current.

package/index.d.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+export interface MathError {
+  code: string;
+  message: string;
+  /** Zero-based UTF-16 offset in the formula. */
+  offset: number;
+  command?: string;
+  messageTruncated?: boolean;
+  commandTruncated?: boolean;
+  /** True only when refused oversized source is not embedded in diagnostic SVG. */
+  sourceOmitted?: boolean;
+}
+export interface RenderOptions {
+  displayMode?: boolean;
+  maxWidth?: number;
+  screen?: {fontSize: number; pixelRatio: number; dark: boolean};
+}
+export interface RenderResult {
+  svg: string;
+  width: number;
+  height: number;
+  depth: number;
+  lines: number;
+  fitted: boolean;
+  errors: MathError[];
+}
+/** Parser nodes are inspectable; the internal node vocabulary can grow. */
+export interface MathNode {type: string; [field: string]: unknown}
+/** Browser nodes (including Element, Document and DocumentFragment) satisfy this
+ * structural type without requiring the DOM type library in server projects. */
+export interface MathContainer {readonly nodeType: number}
+export const version: string;
+/** Oversized source returns a bounded resource-limit diagnostic with sourceOmitted. */
+export function render(source: unknown, options?: RenderOptions): RenderResult;
+export function renderToString(source: unknown, options?: RenderOptions): string;
+export function parse(source: string): MathNode;
+export function fit(container: MathContainer): number;
+export function observe(container: MathContainer): () => void;
+declare const RapierMath: Readonly<{
+  version: typeof version; render: typeof render; renderToString: typeof renderToString;
+  parse: typeof parse; fit: typeof fit; observe: typeof observe;
+}>;
+export default RapierMath;