/* 0.4.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 * * @category Web Component */ 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 * @category Virtual Keyboard */ export type VirtualKeyboardPolicy = 'auto' | 'manual'; 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; 'virtual-keyboard-layer-change': Event; } } /** * These attributes of the `` element correspond to the * [MathfieldOptions] properties. * * @category Web Component */ 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^{2n+1}<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 {(x,y)|0<=x<=1 and 0<=y<=x} * - \int\_{the unit square} 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 represent a DOM element that displays * math equations. * * 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. * * It inherits many useful properties and methods from `HTMLElement` such * as `style`, `tabIndex`, `addEventListener()`, `getAttribute()`, etc... * * It is typically used to render a single equation. * * To render multiple equations, use multiple instances of `MathfieldElement`. * * The `MathfieldElement` class provides special properties and methods to * control the display and behavior of `` elements. * * * You will usually instantiate a `MathfieldElement` using the * `` tag in HTML. However, if necessary you can also create * it programmatically using `new MathfieldElement()`. * * * ```javascript * // 1. Create a new MathfieldElement * const mf = new MathfieldElement(); * * // 2. Attach it to the DOM * document.body.appendChild(mf); * ``` * * The `MathfieldElement` constructor has an optional argument of * `MathfieldOptions` to configure the element. The options can also * be modified later: * * ```javascript * // Setting options during construction * const mf = new MathfieldElement({ smartFence: false }); * * // Modifying options after construction * mf.smartFence = true; * ``` * * #### 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"); * ``` *
* * | CSS Variable | Usage | * |:---|:---| * | `--hue` | Hue of the highlight color and the caret | * | `--contains-highlight-background-color` | Backround property for items that contain the caret | * | `--primary-color` | Primary accent color, used for example in the virtual keyboard | * | `--text-font-family` | The font stack used in text mode | * | `--smart-fence-opacity` | Opacity of a smart fence (default is 50%) | * | `--smart-fence-color` | Color of a smart fence (default is current color) | * *
* * 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 * * To style the virtual keyboard toggle, use the `virtual-keyboard-toggle` CSS * part. To use it, define a CSS rule with a `::part()` selector * for example: * * ```css * math-field::part(virtual-keyboard-toggle) { * color: red; * } * ``` * * * #### 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. * * The property can also be changed directly on the `MathfieldElement` object: * * ```javascript * getElementById('mf').value = "\\sin x"; * getElementById('mf').letterShapeStyle = "text"; * ``` * * The values of attributes and properties are reflected, which means you can * change one or the other, for example: * * ```javascript * getElementById('mf').setAttribute('letter-shape-style', 'french'); * console.log(getElementById('mf').letterShapeStyle); * // Result: "french" * getElementById('mf').letterShapeStyle ='tex; * console.log(getElementById('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 `MathfieldOptions` for more details about these options. * * In addition, the following [global attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes) * can also be used: * - `class` * - `data-*` * - `hidden` * - `id` * - `item*` * - `style` * - `tabindex` * * * #### MathfieldElement Events * * Listen to these events by using `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 Web Component * @keywords zindex, events, attribute, attributes, property, properties, parts, variables, css, mathfield, mathfieldelement */ export declare class MathfieldElement extends HTMLElement implements Mathfield { static version: string; 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; static openUrl: (href: string) => void; /** * Support for [Trusted Type](https://w3c.github.io/webappsec-trusted-types/dist/spec/). * * 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. */ static createHTML: (html: string) => any; /** * 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 `