/* 0.109.1 */ import type { Selector } from './commands'; import type { Expression, LatexSyntaxError, MacroDictionary, Offset, ParseMode, Registers, Style, Selection, Range, OutputFormat, ElementInfo, InsertOptions } from './core-types'; import type { InsertStyleHook, Mathfield } from './mathfield'; import type { InlineShortcutDefinitions, Keybinding, MathfieldOptions } from './options'; import type { MenuItem } from './ui-menu-types'; import type { ComputeEngine } from '@cortex-js/compute-engine'; import { KeyboardModifiers } from './ui-events-types'; /** * **Event re-targeting** * * Some events bubble up through the DOM tree, so that they are detectable by * any element on the page. * * Bubbling events fired from within shadow DOM are re-targeted so that, to any * listener external to your component, they appear to come from your * component itself. * * **Custom Event Bubbling** * * By default, a bubbling custom event fired inside shadow DOM will stop * bubbling when it reaches the shadow root. * * To make a custom event pass through shadow DOM boundaries, you must set * both the `composed` and `bubbles` flags to true. * * The `move-out` event signals that the user pressed an **arrow** key or * **tab** key but there was no navigation possible inside the mathfield. * * This event provides an opportunity to handle this situation, for example * by focusing an element adjacent to the mathfield. * * If the event is canceled (i.e. `evt.preventDefault()` is called inside your * event handler), the default behavior is to play a "plonk" sound. * * @category Mathfield */ export type MoveOutEvent = { direction: 'forward' | 'backward' | 'upward' | 'downward'; }; /** * - `"auto"`: the virtual keyboard is triggered when a * mathfield is focused on a touch capable device. * - `"manual"`: the virtual keyboard is not triggered automatically * - `"sandboxed"`: the virtual keyboard is displayed in the current browsing * context (iframe) if it has a defined container or is the top-level browsing * context. * * @category Virtual Keyboard */ export type VirtualKeyboardPolicy = 'auto' | 'manual' | 'sandboxed'; declare global { /** * Map the custom event names to types * @internal */ interface HTMLElementEventMap { 'mode-change': CustomEvent; 'mount': Event; 'unmount': Event; 'move-out': CustomEvent; 'read-aloud-status-change': Event; 'selection-change': Event; 'undo-state-change': CustomEvent; 'before-virtual-keyboard-toggle': Event; 'virtual-keyboard-toggle': Event; } } /** * These attributes of the `` element correspond to matching properties. * * @category Mathfield */ export interface MathfieldElementAttributes { [key: string]: unknown; 'default-mode': string; 'letter-shape-style': string; 'min-font-scale': number; 'max-matrix-cols': number; 'popover-policy': string; /** * The LaTeX string to insert when the spacebar is pressed (on the physical or * virtual keyboard). Empty by default. Use `\;` for a thick space, `\:` for * a medium space, `\,` for a thin space. */ 'math-mode-space': string; /** When true, the user cannot edit the mathfield. */ 'read-only': boolean; 'remove-extraneous-parentheses': boolean; /** * When `on` and an open fence is entered via `typedText()` it will * generate a contextually appropriate markup, for example using * `\left...\right` if applicable. * * When `off`, the literal value of the character will be inserted instead. */ 'smart-fence': string; /** * When `on`, during text input the field will switch automatically between * 'math' and 'text' mode depending on what is typed and the context of the * formula. If necessary, what was previously typed will be 'fixed' to * account for the new info. * * For example, when typing "if x >0": * * | Type | Interpretation | * |---:|:---| * | "i" | math mode, imaginary unit | * | "if" | text mode, english word "if" | * | "if x" | all in text mode, maybe the next word is xylophone? | * | "if x >" | "if" stays in text mode, but now "x >" is in math mode | * | "if x > 0" | "if" in text mode, "x > 0" in math mode | * * Smart Mode is `off` by default. * * Manually switching mode (by typing `alt/option+=`) will temporarily turn * off smart mode. * * * **Examples** * * - slope = rise/run * - If x > 0, then f(x) = sin(x) * - x^2 + sin (x) when x > 0 * - When x<0, x^b;2n+1d;<0 * - Graph x^2 -x+3 =0 for 0<=x<=5 * - Divide by x-3 and then add x^2-1 to both sides * - Given g(x) = 4x – 3, when does g(x)=0? * - Let D be the set b;(x,y)|0<=x<=1 and 0<=y<=xd; * - \int\_b;the unit squared; f(x,y) dx dy * - For all n in NN * */ 'smart-mode': string; /** * When `on`, when a digit is entered in an empty superscript, the cursor * leaps automatically out of the superscript. This makes entry of common * polynomials easier and faster. If entering other characters (for example * "n+1") the navigation out of the superscript must be done manually (by * using the cursor keys or the spacebar to leap to the next insertion * point). * * When `off`, the navigation out of the superscript must always be done * manually. * */ 'smart-superscript': string; /** * Maximum time, in milliseconds, between consecutive characters for them to be * considered part of the same shortcut sequence. * * A value of 0 is the same as infinity: any consecutive character will be * candidate for an inline shortcut, regardless of the interval between this * character and the previous one. * * A value of 750 will indicate that the maximum interval between two * characters to be considered part of the same inline shortcut sequence is * 3/4 of a second. * * This is useful to enter "+-" as a sequence of two characters, while also * supporting the "±" shortcut with the same sequence. * * The first result can be entered by pausing slightly between the first and * second character if this option is set to a value of 250 or so. * * Note that some operations, such as clicking to change the selection, or * losing the focus on the mathfield, will automatically timeout the * shortcuts. */ 'inline-shortcut-timeout': string; 'script-depth': string; /** When the mathfield is empty, display this placeholder LaTeX string * instead */ 'placeholder': string; /** * - `"auto"`: the virtual keyboard is triggered when a * mathfield is focused on a touch capable device. * - `"manual"`: the virtual keyboard is not triggered automatically * - `"sandboxed"`: the virtual keyboard is displayed in the current browsing * context (iframe) if it has a defined container or is the top-level browsing * context. * */ 'math-virtual-keyboard-policy': VirtualKeyboardPolicy; /** * Specify the `targetOrigin` parameter for * [postMessage](https://developer.mozilla.org/en/docs/Web/API/Window/postMessage) * to send control messages from child to parent frame to remote control * of mathfield component. * * **Default**: `window.origin` */ 'virtual-keyboard-target-origin': string; } /** * * The `MathfieldElement` class is a DOM element that provides a math input * field. * * It is a subclass of the standard * [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) * class and as such inherits all of its properties and methods, such * as `style`, `tabIndex`, `addEventListener()`, `getAttribute()`, etc... * * The `MathfieldElement` class provides additional properties and methods to * control the display and behavior of `` elements. * * **To instantiate a `MathfieldElement`** use the `` tag in HTML. * You can also instantiate a `MathfieldElement` programmatically using * `new MathfieldElement()`. * * ```javascript * // 1. Create a new MathfieldElement * const mf = new MathfieldElement(); * * // 2. Attach it to the DOM * document.body.appendChild(mf); * * // 3. Modifying options after the mathfield has been attached to the DOM * mf.addEventListener("mount"), () => { * mf.smartFence = true; * }); * ``` * * Read more about customizing the appearance and behavior of the mathfield in * the [Customizing the Mathfield](/mathfield/guides/customizing/) guide. * * * #### MathfieldElement CSS Variables * * **To customize the appearance of the mathfield**, declare the following CSS * variables (custom properties) in a ruleset that applies to the mathfield. * * ```css * math-field { * --hue: 10 // Set the highlight color and caret to a reddish hue * } * ``` * * Alternatively you can set these CSS variables programatically: * * ```js * document.body.style.setProperty("--hue", "10"); * ``` * * Read more about the [CSS variables](/mathfield/guides/customizing/#css-variables) available for customization. * * You can customize the appearance and zindex of the virtual keyboard panel * with some CSS variables associated with a selector that applies to the * virtual keyboard panel container. * * Read more about [customizing the virtual keyboard appearance](/mathfield/guides/virtual-keyboards/#custom-appearance) * * #### MathfieldElement CSS Parts * * In addition to the CSS variables, the mathfield exposes [CSS * parts that can be used to style the mathfield](/mathfield/guides/customizing/#mathfield-parts). * * For example, to hide the menu button: * * ```css * math-field::part(menu-toggle) { * display: none; * } * ``` * * * #### MathfieldElement Attributes * * An attribute is a key-value pair set as part of the `` tag: * * ```html * * ``` * * The supported attributes are listed in the table below with their * corresponding property, which can be changed directly on the * `MathfieldElement` object: * * ```javascript * mf.value = "\\sin x"; * mf.letterShapeStyle = "tex"; * ``` * * The values of attributes and properties are reflected, which means you can * change one or the other, for example: * * ```javascript * mf.setAttribute("letter-shape-style", "french"); * console.log(mf.letterShapeStyle); * // Result: "french" * * mf.letterShapeStyle ="tex"; * console.log(mf.getAttribute("letter-shape-style"); * // Result: "tex" * ``` * * An exception is the `value` property, which is not reflected on the `value` * attribute. For consistency with other DOM elements, the `value` attribute * remains at its initial value. * * *
* * | Attribute | Property | * |:---|:---| * | `disabled` | `mf.disabled` | * | `default-mode` | `mf.defaultMode` | * | `letter-shape-style` | `mf.letterShapeStyle` | * | `min-font-scale` | `mf.minFontScale` | * | `max-matrix-cols` | `mf.maxMatrixCols` | * | `popover-policy` | `mf.popoverPolicy` | * | `math-mode-space` | `mf.mathModeSpace` | * | `read-only` | `mf.readOnly` | * | `remove-extraneous-parentheses` | `mf.removeExtraneousParentheses` | * | `smart-fence` | `mf.smartFence` | * | `smart-mode` | `mf.smartMode` | * | `smart-superscript` | `mf.smartSuperscript` | * | `inline-shortcut-timeout` | `mf.inlineShortcutTimeout` | * | `script-depth` | `mf.scriptDepth` | * | `value` | `value` | * | `math-virtual-keyboard-policy` | `mathVirtualKeyboardPolicy` | * *
* * See [more details about these attributes](#mathfieldelementattributes). * * In addition, the following DOM elements [global attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes) * are supported: * - `class` * - `data-*` * - `hidden` * - `id` * - `item*` * - `style` * - `tabindex` * * * #### MathfieldElement Events * * **To listen to these events** use `mf.addEventListener()`. For events with * additional arguments, the arguments are available in `event.detail`. * *
* * | Event Name | Description | * |:---|:---| * | `beforeinput` | The value of the mathfield is about to be modified. | * | `input` | The value of the mathfield has been modified. This happens on almost every keystroke in the mathfield. The `evt.data` property includes a copy of `evt.inputType`. See `InputEvent` | * | `change` | The user has committed the value of the mathfield. This happens when the user presses **Return** or leaves the mathfield. | * | `selection-change` | The selection (or caret position) in the mathfield has changed | * | `mode-change` | The mode (`math`, `text`) of the mathfield has changed | * | `undo-state-change` | The state of the undo stack has changed. The `evt.detail.type` indicate if a snapshot was taken or an undo performed. | * | `read-aloud-status-change` | The status of a read aloud operation has changed | * | `before-virtual-keyboard-toggle` | The visibility of the virtual keyboard panel is about to change. The `evt.detail.visible` property indicate if the keyboard will be visible or not. Listen for this event on `window.mathVirtualKeyboard` | * | `virtual-keyboard-toggle` | The visibility of the virtual keyboard panel has changed. Listen for this event on `window.mathVirtualKeyboard` | * | `geometrychange` | The geometry of the virtual keyboard has changed. The `evt.detail.boundingRect` property is the new bounding rectangle of the virtual keyboard. Listen for this event on `window.mathVirtualKeyboard` | * | `blur` | The mathfield is losing focus | * | `focus` | The mathfield is gaining focus | * | `move-out` | The user has pressed an **arrow** key or the **tab** key, but there is nowhere to go. This is an opportunity to change the focus to another element if desired.
`detail: \{direction: 'forward' | 'backward' | 'upward' | 'downward'\}` **cancellable**| * | `keypress` | The user pressed a physical keyboard key | * | `mount` | The element has been attached to the DOM | * | `unmount` | The element is about to be removed from the DOM | * *
* @category Mathfield * @keywords zindex, events, attribute, attributes, property, properties, parts, variables, css, mathfield, mathfieldelement * */ export declare class MathfieldElement extends HTMLElement implements Mathfield { static version: string; /** @internal */ static get formAssociated(): boolean; /** * Private lifecycle hooks. * If adding a 'boolean' attribute, add its default value to getOptionsFromAttributes * @internal */ static get optionsAttributes(): Readonly>; /** * Custom elements lifecycle hooks * @internal */ static get observedAttributes(): readonly string[]; /** * A URL fragment pointing to the directory containing the fonts * necessary to render a formula. * * These fonts are available in the `/fonts` directory of the npm package. * * Customize this value to reflect where you have copied these fonts, * or to use the CDN version. * * The default value is `"./fonts"`. Use `null` to prevent * any fonts from being loaded. * * Changing this setting after the mathfield has been created will have * no effect. * * ```javascript * { * // Use the CDN version * fontsDirectory: '' * } * ``` * * ```javascript * { * // Use a directory called "fonts", located next to the * // `mathlive.js` (or `mathlive.mjs`) file. * fontsDirectory: './fonts' * } * ``` * * ```javascript * { * // Use a directory located at the root of your website * fontsDirectory: 'https://example.com/fonts' * } * ``` * */ static get fontsDirectory(): string | null; static set fontsDirectory(value: string | null); static openUrl: (href: string) => void; /** @internal */ get fontsDirectory(): never; /** @internal */ set fontsDirectory(_value: unknown); /** @internal */ private static _fontsDirectory; /** * A URL fragment pointing to the directory containing the optional * sounds used to provide feedback while typing. * * Some default sounds are available in the `/dist/sounds` directory of the SDK. * * Use `null` to prevent any sound from being loaded. * @category Virtual Keyboard */ static get soundsDirectory(): string | null; static set soundsDirectory(value: string | null); /** @internal */ get soundsDirectory(): never; /** @internal */ set soundsDirectory(_value: unknown); /** @internal */ private static _soundsDirectory; /** * When a key on the virtual keyboard is pressed, produce a short haptic * feedback, if the device supports it. * @category Virtual Keyboard */ static keypressVibration: boolean; /** * When a key on the virtual keyboard is pressed, produce a short audio * feedback. * * If the property is set to a `string`, the same sound is played in all * cases. Otherwise, a distinct sound is played: * * - `delete` a sound played when the delete key is pressed * - `return` ... when the return/tab key is pressed * - `spacebar` ... when the spacebar is pressed * - `default` ... when any other key is pressed. This property is required, * the others are optional. If they are missing, this sound is played as * well. * * The value of the properties should be either a string, the name of an * audio file in the `soundsDirectory` directory or `null` to suppress * the sound. * * If the `soundsDirectory` is `null`, no sound will be played. * * @category Virtual Keyboard */ static get keypressSound(): Readonly<{ spacebar: null | string; return: null | string; delete: null | string; default: null | string; }>; static set keypressSound(value: null | string | { spacebar?: null | string; return?: null | string; delete?: null | string; default: null | string; }); /** @internal */ private static _keypressSound; /** @ignore */ private static _plonkSound; /** * Sound played to provide feedback when a command has no effect, for example * when pressing the spacebar at the root level. * * The property is either: * - a string, the name of an audio file in the `soundsDirectory` directory * - `null` to turn off the sound * * If the `soundsDirectory` is `null`, no sound will be played. * */ static get plonkSound(): string | null; static set plonkSound(value: string | null); /** @internal */ private static audioBuffers; /** @internal */ private static _audioContext; /** @internal */ private static get audioContext(); /** * Support for [Trusted Type](https://www.w3.org/TR/trusted-types/). * * This optional function will be called before a string of HTML is * injected in the DOM, allowing that string to be sanitized * according to a policy defined by the host. * * Consider using this option if you are displaying untrusted content. Read more about [Security Considerations](/mathfield/guides/security/) * */ static createHTML: (html: string) => any; /** * Indicates which speech engine to use for speech output. * * Use `local` to use the OS-specific TTS engine. * * Use `amazon` for Amazon Text-to-Speech cloud API. You must include the * AWS API library and configure it with your API key before use. * * **See** * {@link mathfield/guides/speech/ | Guide: Speech} * @category Speech */ static get speechEngine(): 'local' | 'amazon'; static set speechEngine(value: 'local' | 'amazon'); /** @internal */ private static _speechEngine; /** * Sets the speed of the selected voice. * * One of `x-slow`, `slow`, `medium`, `fast`, `x-fast` or a value as a * percentage. * * Range is `20%` to `200%` For example `200%` to indicate a speaking rate * twice the default rate. * @category Speech */ static get speechEngineRate(): string; static set speechEngineRate(value: string); /** @internal */ private static _speechEngineRate; /** * Indicates the voice to use with the speech engine. * * This is dependent on the speech engine. For Amazon Polly, see here: * https://docs.aws.amazon.com/polly/latest/dg/voicelist.html * * @category Speech */ static get speechEngineVoice(): string; static set speechEngineVoice(value: string); /** @internal */ private static _speechEngineVoice; /** * The markup syntax to use for the output of conversion to spoken text. * * Possible values are `ssml` for the SSML markup or `mac` for the macOS * markup, i.e. `[[ltr]]`. * @category Speech * */ static get textToSpeechMarkup(): '' | 'ssml' | 'ssml_step' | 'mac'; static set textToSpeechMarkup(value: '' | 'ssml' | 'ssml_step' | 'mac'); /** @internal */ private static _textToSpeechMarkup; /** * Specify which set of text to speech rules to use. * * A value of `mathlive` indicates that the simple rules built into MathLive * should be used. * * A value of `sre` indicates that the Speech Rule Engine from Volker Sorge * should be used. * * **(Caution)** SRE is not included or loaded by MathLive. For this option to * work SRE should be loaded separately. * * **See** * {@link mathfield/guides/speech/ | Guide: Speech} * @category Speech */ static get textToSpeechRules(): 'mathlive' | 'sre'; static set textToSpeechRules(value: 'mathlive' | 'sre'); /** @internal */ private static _textToSpeechRules; /** * A set of key/value pairs that can be used to configure the speech rule * engine. * * Which options are available depends on the speech rule engine in use. * There are no options available with MathLive's built-in engine. The * options for the SRE engine are documented * {@link https://github.com/zorkow/speech-rule-engine | here} * @category Speech */ static get textToSpeechRulesOptions(): Readonly>; static set textToSpeechRulesOptions(value: Record); /** @internal */ private static _textToSpeechRulesOptions; /** @category Speech */ static speakHook: (text: string) => void; /** @category Speech */ static readAloudHook: (element: HTMLElement, text: string) => void; /** * The locale (language + region) to use for string localization. * * If none is provided, the locale of the browser is used. * @category Localization * */ static get locale(): string; static set locale(value: string); /** @internal */ get locale(): never; /** @internal */ set locale(_value: unknown); /** * An object whose keys are a locale string, and whose values are an object of * string identifier to localized string. * * **Example** * ```js example mf.strings = { "fr-CA": { "tooltip.undo": "Annuler", "tooltip.redo": "Refaire", } } ``` * * If the locale is already supported, this will override the existing * strings. If the locale is not supported, it will be added. * * @category Localization */ static get strings(): Readonly>>; static set strings(value: Record>); /** @internal */ get strings(): never; /** @internal */ set strings(_val: unknown); /** * When switching from a tab to one that contains a mathfield that was * previously focused, restore the focus to the mathfield. * * This is behavior consistent with `