mathlive

/* 0.59.0 */ import { MathfieldOptions } from './options'; import { Selector } from './commands'; import { InsertOptions, Mathfield, OutputFormat, Range } from './mathfield'; import { MathfieldErrorCode, ParseMode, ParserErrorCode, Style } from './core'; /** * The `math-error` custom event signals an error while parsing an expression. * * ```javascript * document.getElementById('mf').addEventListener('math-error', (ev) => { * const err = ev.detail; * console.warn(err.code + (err.arg ? ': ' + err.arg : '') + * '\n%c| ' + err.before + '%c' + err.after + * '\n%c| ' + String(' ').repeat(err.before.length) + * '▲', * 'font-weight: bold', * 'font-weight: normal; color: rgba(160, 160, 160)', * 'font-weight: bold; color: hsl(4deg, 90%, 50%)' * ); * }); * ``` */ export declare type MathErrorEvent = { code: ParserErrorCode | MathfieldErrorCode; arg?: string; latex?: string; before?: string; after?: string; }; /** * The `keystroke` event is fired when a keystroke is about to be procesed. * The event is cancellable, which wills suprress further handling of the event. * */ export declare type KeystrokeEvent = { /** A string descring the keystroke, for example `"Alt-KeyU". See [W3C UIEvents](https://www.w3.org/TR/uievents/#keys-keyvalues) * for more information on the format of the descriptor. * */ keystroke: string; /** The native keyboard event */ event?: KeyboardEvent; }; /** * The `focus-out` event signals that the mathfield has lost focus through keyboard * navigation with arrow keys or the tab key. * * The event `detail.direction` property indicates the direction the cursor * was moving which can be useful to decide which element to focus next. * * The event is cancelable, which will prevent the field from losing focus. * * ```javascript * mfe.addEventListener('focus-out', (ev) => { * console.log("Losing focus ", ev.detail.direction); * }); * ``` */ export declare type FocusOutEvent = { direction: 'forward' | 'backward' | 'upward' | 'downward'; }; declare global { /** * Map the custom event names to types * @internal */ interface DocumentEventMap { ['math-error']: CustomEvent<MathErrorEvent>; ['keystroke']: CustomEvent<KeystrokeEvent>; ['focus-out']: CustomEvent<FocusOutEvent>; } } /** * The `MathfieldElement` class provides special properties and * methods to control the display and behavior of `<math-field>` * elements. * * It inherits many useful properties and methods from [[`HTMLElement`]] such * as `style`, `tabIndex`, `addEventListener()`, `getAttribute()`, etc... * * To create a new `MathfieldElement`: * * ```javascript * // 1. Create a new MathfieldElement * const mfe = new MathfieldElement(); * // 2. Attach it to the DOM * document.body.appendChild(mfe); * ``` * * 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 mfe = new MathfieldElement({smartFence: false}); * // Modifying options after construction * mfe.setOptions({smartFence: true}); * ``` * * ### CSS Variables * * To customize the appearance of the mathfield, declare the following CSS * variables (custom properties) in a ruleset that applied to the mathfield. * ```css * math-field { * --hue: 10 // Set the highlight color and caret to a reddish hue * } * ``` * * | CSS Variable | Usage | * |:---|:---| * | `--hue` | Hue of the highlight color and the caret | * | `--highlight` | Color of the selection | * | `--highlight-inactive` | Color of the selection, when the mathfield is not focused | * | `--caret` | Color of the caret/insertion point | * | `--primary` | Primary accent color, used for example in the virtual keyboard | * | `--text-font-family` | The font stack used in text mode | * | `--keyboard-zindex` | The z-index attribute of the virtual keyboard panel | * * ### 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; * } * ``` * * * ### Attributes * * An attribute is a key-value pair set as part of the tag: * * ```html * <math-field locale="fr"></math-field> * ``` * * The supported attributes are listed in the table below with their correspnding * property. * * The property can be changed either directly on the * `MathfieldElement` object, or using `setOptions()` if it is prefixed with * `options.`, for example * ```javascript * getElementById('mf').value = '\\sin x'; * getElementById('mf').setOptions({horizontalSpacingScale: 1.1}); * ``` * * The values of attributes and properties are reflected, which means you can change one or the * other, for example: * ```javascript * getElementById('mf').setAttribute('virtual-keyboard-mode', 'manual'); * console.log(getElementById('mf').getOption('virtualKeyboardMode')); * // Result: "manual" * getElementById('mf').setOptions({virtualKeyboardMode: 'onfocus'); * console.log(getElementById('mf').getAttribute('virtual-keyboard-mode'); * // Result: 'onfocus' * ``` * * An exception is the `value` property, which is not reflected on the `value` * attribute: the `value` attribute remains at its initial value. * * * | Attribute | Property | * |:---|:---| * | `disabled` | `disabled` | * | `default-mode` | `options.defaultMode` | * | `fonts-directory` | `options.fontsDirectory` | * | `horizontal-spacing-scale` | `options.horizontalSpacingScale` | * | `ignore-spacebar-in-math-mode` | `options.ignoreSpacbarInMathMode` | * | `inline-shortcut-timeout` | `options.inlineShortcutTimeout` | * | `keypress-vibration` | `options.keypressVibration` | * | `letter-shape-style` | `options.letterShapeStyle` | * | `locale` | `options.locale` | * | `read-only` | `options.readOnly` | * | `remove-extraneous-parentheses` | `options.removeExtraneousParentheses` | * | `smart-fence` | `options.smartFence` | * | `smart-mode` | `options.smartMode` | * | `smart-superscript` | `options.superscript` | * | `speech-engine` | `options.speechEngine` | * | `speech-engine-rate` | `options.speechEngineRate` | * | `speech-engine-voice` | `options.speechEngineVoice` | * | `text-to-speech-markup` | `options.textToSpeechMarkup` | * | `text-to-speech-rules` | `options.textToSpeechRules` | * | `value` | value | * | `virtual-keyboard-layout` | `options.keyboardLayout` | * | `virtual-keyboard-mode` | `options.keyboardMode` | * | `virtual-keyboard-theme` | `options.keyboardTheme` | * | `virtual-keyboards` | `options.keyboards` | * * 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` * * * ### Events * * Listen to these events by using `addEventListener()`. For events with additional * arguments, the arguments are availble in `event.detail`. * * | Event Name | Description | * |:---|:---| * | `input` | The value of the mathfield has been modified. This happens on almost every keystroke in the mathfield. | * | `change` | The user has commited 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 | * | `read-aloud-status-change` | The status of a read aloud operation has changed | * | `virtual-keyboard-toggle` | The visibility of the virtual keyboard panel has changed | * | `blur` | The mathfield is losing focus | * | `focus` | The mathfield is gaining focus | * | `focus-out` | The user is navigating out of the mathfield, typically using the keyboard<br> `detail: {direction: 'forward' | 'backward' | 'upward' | 'downward'}` **cancellable**| * | `math-error` | A parsing or configuration error happened <br> `detail: ErrorListener<ParserErrorCode | MathfieldErrorCode>` | * | `keystroke` | The user typed a keystroke with a physical keyboard <br> `detail: {keystroke: string, event: KeyboardEvent}` | * | `mount` | The element has been attached to the DOM | * | `unmount` | The element is about to be removed from the DOM | * */ export declare class MathfieldElement extends HTMLElement implements Mathfield { #private; /** * Private lifecycle hooks * @internal */ static get optionsAttributes(): { [attribute: string]: 'number' | 'boolean' | 'string'; }; /** * Custom elements lifecycle hooks * @internal */ static get observedAttributes(): string[]; /** * To create programmatically a new mahfield use: * ```javascript let mfe = new MathfieldElement(); // Set initial value and options mfe.value = "\\frac{\\sin(x)}{\\cos(x)}"; // Options can be set either as an attribute (for simple options)... mfe.setAttribute('virtual-keyboard-layout', 'dvorak'); // ... or using `setOptions()` mfe.setOptions({ virtualKeyboardMode: 'manual', }); // Attach the element to the DOM document.body.appendChild(mfe); * ``` */ constructor(options?: Partial<MathfieldOptions>); get mode(): ParseMode; set mode(value: ParseMode); /** * @category Options */ getOptions<K extends keyof MathfieldOptions>(keys: K[]): Pick<MathfieldOptions, K>; getOptions(): MathfieldOptions; /** * @category Options */ getOption<K extends keyof MathfieldOptions>(key: K): MathfieldOptions[K]; /** * @category Options */ setOptions(options: Partial<MathfieldOptions>): void; /** * Execute a [[`Commands`|command]] defined by a selector. * ```javascript * mfe.executeCommand('add-column-after'); * mfe.executeCommand(['switch-mode', 'math']); * ``` * * @param command - A selector, or an array whose first element * is a selector, and whose subsequent elements are arguments to the selector. * * Selectors can be passed either in camelCase or kebab-case. * * ```javascript * // Both calls do the same thing * mfe.executeCommand('selectAll'); * mfe.executeCommand('select-all'); * ``` */ executeCommand(command: Selector | [Selector, ...any[]]): boolean; /** * @category Accessing and changing the content */ getValue(format?: OutputFormat): string; getValue(start: number, end?: number, format?: OutputFormat): string; getValue(range: Range, format?: OutputFormat): string; getValue(ranges: Range[], format?: OutputFormat): string; /** * @category Accessing and changing the content */ setValue(value?: string, options?: InsertOptions): void; /** * Return true if the mathfield is currently focused (responds to keyboard * input). * * @category Focus * */ hasFocus(): boolean; /** * Sets the focus to the mathfield (will respond to keyboard input). * * @category Focus * */ focus(): void; /** * Remove the focus from the mathfield (will no longer respond to keyboard * input). * * @category Focus * */ blur(): void; /** * Select the content of the mathfield. * @category Selection */ select(): void; /** * Inserts a block of text at the current insertion point. * * This method can be called explicitly or invoked as a selector with * `executeCommand("insert")`. * * After the insertion, the selection will be set according to the * `options.selectionMode`. * * @category Accessing and changing the content */ insert(s: string, options?: InsertOptions): boolean; /** * Updates the style (color, bold, italic, etc...) of the selection or sets * the style to be applied to future input. * * If there is a selection, the style is applied to the selection * * If the selection already has this style, it is removed. * * If the selection has the style partially applied (i.e. only some * sections), it is removed from those sections, and applied to the * entire selection. * * If there is no selection, the style will apply to the next character typed. * * @category Accessing and changing the content */ applyStyle(style: Style): void; /** * The bottom location of the caret (insertion point) in viewport * coordinates. * * See also [[`setCaretPoint`]] * @category Selection */ get caretPoint(): { x: number; y: number; }; set caretPoint(point: { x: number; y: number; }); /** * `x` and `y` are in viewport coordinates. * * Return true if the location of the point is a valid caret location. * * See also [[`caretPoint`]] * @category Selection */ setCaretPoint(x: number, y: number): boolean; /** * Return an array of ranges matching the argument. * * An array is always returned, but it has no element if there are no * matching items. */ find(latex: string): Range[]; /** * Custom elements lifecycle hooks * @internal */ connectedCallback(): void; /** * Custom elements lifecycle hooks * @internal */ disconnectedCallback(): void; /** * Private lifecycle hooks * @internal */ upgradeProperty(prop: string): void; /** * Custom elements lifecycle hooks * @internal */ attributeChangedCallback(name: string, oldValue: unknown, newValue: unknown): void; set disabled(value: boolean); get disabled(): boolean; /** * @category Accessing and changing the content */ set value(value: string); /** * The content of the mathfield as a Latex expression. * ``` * document.querySelector('mf').value = '\\frac{1}{\\pi}' * ``` * @category Accessing and changing the content */ get value(): string; /** * An array of ranges representing the selection. * * It is guaranteed there will be at least one element. If a discontinuous * selection is present, the result will include more than one element. * * @category Selection * */ get selection(): Range[]; /** * * @category Selection */ set selection(value: Range[]); /** * The position of the caret/insertion point, from 0 to `lastPosition`. * * @category Selection * */ get position(): number; /** * @category Selection */ set position(value: number); /** * The last valid position. * @category Selection */ get lastPosition(): number; } export default MathfieldElement; declare global { /** @internal */ interface Window { MathfieldElement: typeof MathfieldElement; } }