Skip to content

Commit ea9c173

Browse files
kelvinsjkedemaine
kelvinsjk
and
edemaine
authored
feat: ESM exports, TypeScript types (#3992)
* feat: add typescript definition files * update typed errorCode Co-authored-by: Erik Demaine <[email protected]> * specific string type on strict option Co-authored-by: Erik Demaine <[email protected]> * types: macros type allow for macro expansion Co-authored-by: Erik Demaine <[email protected]> * types: added TrustContext * types: removed redundant @types, fixed @default syntax error and moved to bottom of comments, changed any token type to object * types: import types in mts from cjs definitions * Non-default ESM exports * Merge katex.d.{ts,mts} to better reflect exports * Add tsconfig.json to specify necessary libs --------- Co-authored-by: Erik Demaine <[email protected]>
1 parent 356b6d5 commit ea9c173

File tree

4 files changed

+270
-13
lines changed

4 files changed

+270
-13
lines changed

‎katex.js‎

Lines changed: 33 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -138,11 +138,40 @@ const renderToHTMLTree = function(
138138
}
139139
};
140140

141+
const version = __VERSION__;
142+
143+
const __domTree = {
144+
Span,
145+
Anchor,
146+
SymbolNode,
147+
SvgNode,
148+
PathNode,
149+
LineNode,
150+
};
151+
152+
// ESM exports
153+
export {
154+
version,
155+
render,
156+
renderToString,
157+
ParseError,
158+
SETTINGS_SCHEMA,
159+
generateParseTree as __parse,
160+
renderToDomTree as __renderToDomTree,
161+
renderToHTMLTree as __renderToHTMLTree,
162+
setFontMetrics as __setFontMetrics,
163+
defineSymbol as __defineSymbol,
164+
defineFunction as __defineFunction,
165+
defineMacro as __defineMacro,
166+
__domTree,
167+
};
168+
169+
// CJS exports and ESM default export
141170
export default {
142171
/**
143172
* Current KaTeX version
144173
*/
145-
version: __VERSION__,
174+
version,
146175
/**
147176
* Renders the given LaTeX into an HTML+MathML combination, and adds
148177
* it as a child to the specified DOM node.
@@ -158,7 +187,7 @@ export default {
158187
*/
159188
ParseError,
160189
/**
161-
* The shema of Settings
190+
* The schema of Settings
162191
*/
163192
SETTINGS_SCHEMA,
164193
/**
@@ -210,16 +239,9 @@ export default {
210239
/**
211240
* Expose the dom tree node types, which can be useful for type checking nodes.
212241
*
213-
* NOTE: This method is not currently recommended for public use.
242+
* NOTE: These methods are not currently recommended for public use.
214243
* The internal tree representation is unstable and is very likely
215244
* to change. Use at your own risk.
216245
*/
217-
__domTree: {
218-
Span,
219-
Anchor,
220-
SymbolNode,
221-
SvgNode,
222-
PathNode,
223-
LineNode,
224-
},
246+
__domTree,
225247
};

‎package.json‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,14 @@
55
"main": "dist/katex.js",
66
"exports": {
77
".": {
8-
"require": "./dist/katex.js",
9-
"import": "./dist/katex.mjs"
8+
"require": {
9+
"types": "./types/katex.d.ts",
10+
"default": "./dist/katex.js"
11+
},
12+
"import": {
13+
"types": "./types/katex.d.ts",
14+
"default": "./dist/katex.mjs"
15+
}
1016
},
1117
"./contrib/auto-render": {
1218
"require": "./dist/contrib/auto-render.js",

‎tsconfig.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"compilerOptions": {
3+
"strict": true,
4+
"lib": ["es2021", "dom"],
5+
"moduleResolution": "bundler",
6+
"forceConsistentCasingInFileNames": true
7+
}
8+
}

‎types/katex.d.ts‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
// Adapted from
2+
// - https://katex.org/docs/options
3+
// - https://katex.org/docs/api
4+
// - https://katex.org/docs/error
5+
// for v0.16.11 on 2024/12/01
6+
// with some references from https://www.npmjs.com/package/@types/katex
7+
8+
/**
9+
* For the `trust` option in `KatexOptions`, a custom function
10+
* `handler(context)` can be provided to customize behavior depending on the
11+
* context (command, arguments e.g. a URL, etc.)
12+
* @see https://katex.org/docs/options
13+
*/
14+
export type TrustContext =
15+
| { command: "\\url", url: string, protocol?: string }
16+
| { command: "\\href", url: string, protocol?: string }
17+
| { command: "\\includegraphics", url: string, protocol?: string }
18+
| { command: "\\htmlClass", class: string }
19+
| { command: "\\htmlId", id: string }
20+
| { command: "\\htmlStyle", style: string }
21+
| { command: "\\htmlData", attributes: Record<string, string> }
22+
23+
/**
24+
* Options for `katex.render` and `katex.renderToString`.
25+
* @see https://katex.org/docs/options
26+
*/
27+
export interface KatexOptions {
28+
/**
29+
* If `true` the math will be rendered in display mode.
30+
* If `false` the math will be rendered in inline mode.
31+
* @see https://katex.org/docs/options
32+
*
33+
* @default false
34+
*/
35+
displayMode?: boolean;
36+
/**
37+
* Determines the markup language of the output. The valid choices are:
38+
* - `html`: Outputs KaTeX in HTML only.
39+
* - `mathml`: Outputs KaTeX in MathML only.
40+
* - `htmlAndMathml`: Outputs HTML for visual rendering and includes MathML
41+
* for accessibility.
42+
*
43+
* @default "htmlAndMathml"
44+
*/
45+
output?: "html" | "mathml" | "htmlAndMathml";
46+
/**
47+
* If `true`, display math has `\tag`s rendered on the left instead of the
48+
* right, like `\usepackage[leqno]{amsmath}` in LaTeX.
49+
*
50+
* @default false
51+
*/
52+
leqno?: boolean;
53+
/**
54+
* If `true`, display math renders flush left with a `2em` left margin,
55+
* like `\documentclass[fleqn]` in LaTeX with the `amsmath` package.
56+
*
57+
* @default false
58+
*/
59+
fleqn?: boolean;
60+
/**
61+
* If `true`, KaTeX will throw a `ParseError` when it encounters an
62+
* unsupported command or invalid LaTeX.
63+
* If `false`, KaTeX will render unsupported commands as text, and render
64+
* invalid LaTeX as its source code with hover text giving the error, in
65+
* the color given by `errorColor`.
66+
*
67+
* @default true
68+
*/
69+
throwOnError?: boolean;
70+
/**
71+
* A color string given in the format `"#XXX"` or `"#XXXXXX"`. This option
72+
* determines the color that unsupported commands and invalid LaTeX are
73+
* rendered in when `throwOnError` is set to `false`.
74+
*
75+
* @default "#cc0000"
76+
*/
77+
errorColor?: string;
78+
/**
79+
* A collection of custom macros.
80+
* @see https://katex.org/docs/options
81+
*/
82+
macros?: Record<string, string | object | ((macroExpander:object) => string | object)>;
83+
/**
84+
* Specifies a minimum thickness, in ems, for fraction lines, `\sqrt` top
85+
* lines, `{array}` vertical lines, `\hline`, `\hdashline`, `\underline`,
86+
* `\overline`, and the borders of `\fbox`, `\boxed`, and `\fcolorbox`.
87+
* The usual value for these items is `0.04`, so for `minRuleThickness`
88+
* to be effective it should probably take a value slightly above `0.04`,
89+
* say `0.05` or `0.06`. Negative values will be ignored.
90+
*/
91+
minRuleThickness?: number;
92+
/**
93+
* In early versions of both KaTeX (<0.8.0) and MathJax, the `\color`
94+
* function expected the content to be a function argument, as in
95+
* `\color{blue}{hello}`. In current KaTeX, `\color` is a switch, as in
96+
* `\color{blue}` hello. This matches LaTeX behavior. If you want the old
97+
* `\color` behavior, set option colorIsTextColor to true.
98+
*/
99+
colorIsTextColor?: boolean;
100+
/**
101+
* All user-specified sizes, e.g. in `\rule{500em}{500em}`, will be capped
102+
* to `maxSize` ems. If set to `Infinity` (the default), users can make
103+
* elements and spaces arbitrarily large.
104+
*
105+
* @default Infinity
106+
*/
107+
maxSize?: number;
108+
/**
109+
* Limit the number of macro expansions to the specified number, to prevent
110+
* e.g. infinite macro loops. `\edef` expansion counts all expanded tokens.
111+
* If set to `Infinity`, the macro expander will try to fully expand as in
112+
* LaTeX.
113+
*
114+
* @default 1000
115+
*/
116+
maxExpand?: number;
117+
/**
118+
* If `false` or `"ignore"`, allow features that make writing LaTeX
119+
* convenient but are not actually supported by (Xe)LaTeX
120+
* (similar to MathJax).
121+
* If `true` or `"error"` (LaTeX faithfulness mode), throw an error for any
122+
* such transgressions.
123+
* If `"warn"` (the default), warn about such behavior via `console.warn`.
124+
* Provide a custom function `handler(errorCode, errorMsg, token)` to
125+
* customize behavior depending on the type of transgression (summarized by
126+
* the string code `errorCode` and detailed in `errorMsg`); this function
127+
* can also return `"ignore"`, `"error"`, or `"warn"` to use a built-in
128+
* behavior.
129+
* @see https://katex.org/docs/options
130+
*
131+
* @default "warn"
132+
*/
133+
strict?:
134+
| boolean
135+
| "ignore" | "warn" | "error"
136+
| ((errorCode: string, errorMsg: string, token: object) => boolean | "ignore" | "warn" | "error" | undefined | null);
137+
/**
138+
* If `false` (do not trust input), prevent any commands like
139+
* `\includegraphics` that could enable adverse behavior, rendering them
140+
* instead in `errorColor`.
141+
* If `true` (trust input), allow all such commands.
142+
* Provide a custom function `handler(context)` to customize behavior
143+
* depending on the context (command, arguments e.g. a URL, etc.).
144+
* @see https://katex.org/docs/options
145+
*
146+
* @default false
147+
*/
148+
trust?: boolean | ((context: TrustContext) => boolean);
149+
/**
150+
* Run KaTeX code in the global group. As a consequence, macros defined at
151+
* the top level by `\def` and `\newcommand` are added to the macros
152+
* argument and can be used in subsequent render calls. In LaTeX,
153+
* constructs such as `\begin{equation}` and `$$` create a local group and
154+
* prevent definitions other than `\gdef` from becoming visible outside of
155+
* those blocks, so this is KaTeX's default behavior.
156+
*
157+
* @default false
158+
*/
159+
globalGroup?: boolean;
160+
}
161+
162+
/**
163+
* In-browser rendering
164+
*
165+
* Call the `render` function with a TeX expression and a DOM element to
166+
* render into.
167+
*
168+
* @param {string} tex A TeX expression.
169+
* @param {HTMLElement} element A HTML DOM element.
170+
* @param {KatexOptions} options An options object.
171+
* @returns {void}
172+
* @see https://katex.org/docs/api
173+
*/
174+
export function render(
175+
tex: string,
176+
element: HTMLElement,
177+
options?: KatexOptions,
178+
): void;
179+
180+
/**
181+
* Server-side rendering or rendering to a string
182+
*
183+
* Use the `renderToString` function to generate HTML on the server or to
184+
* generate an HTML string of the rendered math.
185+
*
186+
* @param {string} tex A TeX expression.
187+
* @param {KatexOptions} options An options object.
188+
* @returns {string} The HTML string of the rendered math.
189+
* @see https://katex.org/docs/api
190+
*/
191+
export function renderToString(tex: string, options?: KatexOptions): string;
192+
193+
/**
194+
* If KaTeX encounters an error (invalid or unsupported LaTeX) and
195+
* `throwOnError` hasn't been set to `false`, then `katex.render` and
196+
* `katex.renderToString` will throw an exception of type
197+
* `ParseError`. The message in this error includes some of the LaTeX source
198+
* code, so needs to be escaped if you want to render it to HTML.
199+
* @see https://katex.org/docs/error
200+
*/
201+
export class ParseError implements Error {
202+
constructor(message: string, token?: object);
203+
name: "ParseError";
204+
position: number;
205+
length: number;
206+
rawMessage: string;
207+
message: string;
208+
}
209+
210+
export const version: string;
211+
212+
export as namespace katex;
213+
214+
declare const katex: {
215+
version: string;
216+
render: typeof render;
217+
renderToString: typeof renderToString;
218+
ParseError: typeof ParseError;
219+
};
220+
221+
export default katex;

0 commit comments

Comments
 (0)