Support Preview Pane for Block Math

CHANGELOG.md

@@ -5,6 +5,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+* Display math now shows a preview pane. Inline math previews may be supported in the future. 
+* Added an `initialText` parameter to `insertMathCmd`
+
+**Breaking Changes**
+
+* Added new `isBlockMath` argument to `MathView` constructor
+* `mathPlugin` and `mathPluginSpec` are now functions that accept an `options` parameter
+* The `mathPlugin` state now has an extra flag indicating whether previews are enabled
+
 ## [Releases]
 
 ### [0.2.2] - 2021-06-24

README.md

@@ -14,7 +14,7 @@ The `prosemirror-math` package provides schema and plugins for comfortably writi
 * `src/math-nodeview.ts`: A `NodeView` responsible for rendering and editing math nodes.
 * `style/math.css`: Contains all necessary styling for math nodes to display correctly. This file can easily be modified to achieve your desired appearance.
 
-Additionally, the `docs-src/` contains Aafully-functioning example project that uses webpack generate a static website that includes `prosemirror-math` and all its dependencies. 
+Additionally, the `docs-src/` folder contains a fully-functioning example project that uses webpack to generate a static website that includes `prosemirror-math` and all its dependencies. 
 
 * If you want to the example code as a starting point for your own project, pay special attention to the comments in `docs-src/webpack.config.js`.
 
@@ -132,7 +132,8 @@ let blockMathInputRule = makeBlockMathInputRule(REGEX_BLOCK_MATH_DOLLARS, editor
 
 Choose which plugins you need from the following list, and pass them to your `EditorState` instance, along with the input rules you created.
 
-* `mathPlugin` **(required)** Provides the core functionality of `prosemirror-math`.
+* `mathPlugin` **(required)** Provides the core functionality of `prosemirror-math`. You must set the following options:
+ - `enableBlockPreview`: When `true`, a preview pane is shown when editing block math.
 * `mathBackspaceCmd` *(recommended)* When included in your [keymap](https://prosemirror.net/docs/ref/#keymap.keymap) for the `"Backspace"` key, pressing backspace on the right boundary of a math node will place the cursor inside the math node, rather than deleting it.
 * `insertMathCmd(nodeType: NodeType)` *(optional)* Helper function for creating a command which can be used to insert a math node at the current document position.
 * `mathSerializer` *(recommended)* Attach to the `clipboardTextSerializer` prop of your EditorView. When pasting a selection from a `prosemirror-math` editor to a plain text editor, ensures that the pasted math expressions will be properly delimited by `$...$` and `$$...$$`.
@@ -152,7 +153,7 @@ import { inputRules } from "prosemirror-inputrules";
 
 // plugins (order matters)
 let plugins:Plugin[] = [
- mathPlugin,
+ mathPlugin({ enableBlockPreview: false }),
  keymap({
  "Mod-Space" : insertMathCmd(schema.nodes.math_inline),
  // modify the default keymap chain for backspace

dist/index.d.ts

@@ -5,7 +5,7 @@
 // prosemirror imports
 import { MarkSpec, NodeSpec, Schema, SchemaSpec, NodeType, Mark, Slice, MarkType, Fragment } from "prosemirror-model";
 import { Node as ProseNode } from "prosemirror-model";
-import { EditorState, Transaction, PluginKey } from "prosemirror-state";
+import { Transaction, PluginKey } from "prosemirror-state";
 import { Plugin as ProsePlugin } from "prosemirror-state";
 import { NodeView, EditorView, Decoration } from "prosemirror-view";
 // katex
@@ -30,28 +30,27 @@ interface IMathPluginState {
  * key behavior.
  */
  prevCursorPos: number;
+ /** When TRUE, a preview pane is shown when editing block math. */
+ enableBlockPreview: boolean;
 }
 /**
  * Returns a function suitable for passing as a field in `EditorProps.nodeViews`.
  * @param displayMode TRUE for block math, FALSE for inline math.
  * @see https://prosemirror.net/docs/ref/#view.EditorProps.nodeViews
  */
 declare function createMathView(displayMode: boolean): (node: ProseNode, view: EditorView, getPos: boolean | (() => number)) => MathView;
-declare const mathPlugin: ProsePlugin<IMathPluginState, any>;
-//// INLINE MATH NODEVIEW //////////////////////////////////
-interface ICursorPosObserver {
- /** indicates on which side cursor should appear when this node is selected */
- cursorSide: "start" | "end";
- /** */
- updateCursorPos(state: EditorState): void;
+interface IMathPluginOptions {
+ enableBlockPreview: boolean;
 }
+declare function mathPlugin(options: IMathPluginOptions): ProsePlugin;
+//// INLINE MATH NODEVIEW //////////////////////////////////
 interface IMathViewOptions {
  /** Dom element name to use for this NodeView */
  tagName?: string;
  /** Whether to render this node as display or inline math. */
  katexOptions?: KatexOptions;
 }
-declare class MathView implements NodeView, ICursorPosObserver {
+declare class MathView implements NodeView {
  // nodeview params
  private _node;
  private _outerView;
@@ -60,16 +59,20 @@ declare class MathView implements NodeView, ICursorPosObserver {
  dom: HTMLElement;
  private _mathRenderElt;
  private _mathSrcElt;
+ private _mathEditorElt;
  private _innerView;
  // internal state
  cursorSide: "start" | "end";
+ private _isBlockMath;
  private _katexOptions;
  private _tagName;
- private _isEditing;
- private _onDestroy;
+ private _editorActive;
+ private _renderActive;
  private _mathPluginKey;
  // == Lifecycle ===================================== //
  /**
+ * @param isBlockMath Set to TRUE for block math, FALSE for inline math.
+ * Currently, only affects the math preview pane.
  * @param onDestroy Callback for when this NodeView is destroyed.
  * This NodeView should unregister itself from the list of ICursorPosObservers.
  *
@@ -78,7 +81,10 @@ declare class MathView implements NodeView, ICursorPosObserver {
  * @option tagName HTML tag name to use for this NodeView. If none is provided,
  * will use the node name with underscores converted to hyphens.
  */
- constructor(node: ProseNode, view: EditorView, getPos: (() => number), options: IMathViewOptions | undefined, mathPluginKey: PluginKey<IMathPluginState>, onDestroy?: (() => void));
+ constructor(node: ProseNode, view: EditorView, getPos: (() => number), options: IMathViewOptions | undefined, isBlockMath: boolean, mathPluginKey: PluginKey<IMathPluginState>);
+ /**
+ * Destroy the NodeView, leaving it in an invalid state.
+ */
  destroy(): void;
  /**
  * Ensure focus on the inner editor whenever this node has focus.
@@ -87,7 +93,6 @@ declare class MathView implements NodeView, ICursorPosObserver {
  ensureFocus(): void;
  // == Updates ======================================= //
  update(node: ProseNode, decorations: Decoration[]): boolean;
- updateCursorPos(state: EditorState): void;
  // == Events ===================================== //
  selectNode(): void;
  deselectNode(): void;
@@ -97,6 +102,15 @@ declare class MathView implements NodeView, ICursorPosObserver {
  renderMath(): void;
  // == Inner Editor ================================== //
  dispatchInner(tr: Transaction): void;
+ /**
+ * Mark the render pane as active. CSS controls actual visibility.
+ * @param isPreview If TRUE, we are currently in preview mode.
+ */
+ showRender(isPreview: boolean): void;
+ /**
+ * Mark the render pane as inactive. CSS controls actual visibility.
+ */
+ hideRender(): void;
  openEditor(): void;
  /**
  * Called when the inner ProseMirror editor should close.
@@ -211,5 +225,5 @@ declare class ProseMirrorTextSerializer<S extends Schema<any, any>> {
  serializeNode(node: ProseNode<S>): string | null;
 }
 declare const mathSerializer: ProseMirrorTextSerializer<Schema<"text" | "doc" | "paragraph" | "math_inline" | "math_display", "math_select">>;
-export { MathView, ICursorPosObserver, mathPlugin, createMathView, IMathPluginState, mathSchemaSpec, createMathSchema, mathBackspaceCmd, makeBlockMathInputRule, makeInlineMathInputRule, REGEX_BLOCK_MATH_DOLLARS, REGEX_INLINE_MATH_DOLLARS, REGEX_INLINE_MATH_DOLLARS_ESCAPED, mathSelectPlugin, insertMathCmd, mathSerializer, SchemaSpecNodeT, SchemaSpecMarkT, SchemaNodeT, SchemaMarkT };
+export { MathView, mathPlugin, createMathView, IMathPluginState, mathSchemaSpec, createMathSchema, mathBackspaceCmd, makeBlockMathInputRule, makeInlineMathInputRule, REGEX_BLOCK_MATH_DOLLARS, REGEX_INLINE_MATH_DOLLARS, REGEX_INLINE_MATH_DOLLARS_ESCAPED, mathSelectPlugin, insertMathCmd, mathSerializer, SchemaSpecNodeT, SchemaSpecMarkT, SchemaNodeT, SchemaMarkT };
 //# sourceMappingURL=index.d.ts.map

dist/index.es.d.ts

@@ -5,7 +5,7 @@
 // prosemirror imports
 import { MarkSpec, NodeSpec, Schema, SchemaSpec, NodeType, Mark, Slice, MarkType, Fragment } from "prosemirror-model";
 import { Node as ProseNode } from "prosemirror-model";
-import { EditorState, Transaction, PluginKey } from "prosemirror-state";
+import { Transaction, PluginKey } from "prosemirror-state";
 import { Plugin as ProsePlugin } from "prosemirror-state";
 import { NodeView, EditorView, Decoration } from "prosemirror-view";
 // katex
@@ -30,28 +30,27 @@ interface IMathPluginState {
  * key behavior.
  */
  prevCursorPos: number;
+ /** When TRUE, a preview pane is shown when editing block math. */
+ enableBlockPreview: boolean;
 }
 /**
  * Returns a function suitable for passing as a field in `EditorProps.nodeViews`.
  * @param displayMode TRUE for block math, FALSE for inline math.
  * @see https://prosemirror.net/docs/ref/#view.EditorProps.nodeViews
  */
 declare function createMathView(displayMode: boolean): (node: ProseNode, view: EditorView, getPos: boolean | (() => number)) => MathView;
-declare const mathPlugin: ProsePlugin<IMathPluginState, any>;
-//// INLINE MATH NODEVIEW //////////////////////////////////
-interface ICursorPosObserver {
- /** indicates on which side cursor should appear when this node is selected */
- cursorSide: "start" | "end";
- /** */
- updateCursorPos(state: EditorState): void;
+interface IMathPluginOptions {
+ enableBlockPreview: boolean;
 }
+declare function mathPlugin(options: IMathPluginOptions): ProsePlugin;
+//// INLINE MATH NODEVIEW //////////////////////////////////
 interface IMathViewOptions {
  /** Dom element name to use for this NodeView */
  tagName?: string;
  /** Whether to render this node as display or inline math. */
  katexOptions?: KatexOptions;
 }
-declare class MathView implements NodeView, ICursorPosObserver {
+declare class MathView implements NodeView {
  // nodeview params
  private _node;
  private _outerView;
@@ -60,16 +59,20 @@ declare class MathView implements NodeView, ICursorPosObserver {
  dom: HTMLElement;
  private _mathRenderElt;
  private _mathSrcElt;
+ private _mathEditorElt;
  private _innerView;
  // internal state
  cursorSide: "start" | "end";
+ private _isBlockMath;
  private _katexOptions;
  private _tagName;
- private _isEditing;
- private _onDestroy;
+ private _editorActive;
+ private _renderActive;
  private _mathPluginKey;
  // == Lifecycle ===================================== //
  /**
+ * @param isBlockMath Set to TRUE for block math, FALSE for inline math.
+ * Currently, only affects the math preview pane.
  * @param onDestroy Callback for when this NodeView is destroyed.
  * This NodeView should unregister itself from the list of ICursorPosObservers.
  *
@@ -78,7 +81,10 @@ declare class MathView implements NodeView, ICursorPosObserver {
  * @option tagName HTML tag name to use for this NodeView. If none is provided,
  * will use the node name with underscores converted to hyphens.
  */
- constructor(node: ProseNode, view: EditorView, getPos: (() => number), options: IMathViewOptions | undefined, mathPluginKey: PluginKey<IMathPluginState>, onDestroy?: (() => void));
+ constructor(node: ProseNode, view: EditorView, getPos: (() => number), options: IMathViewOptions | undefined, isBlockMath: boolean, mathPluginKey: PluginKey<IMathPluginState>);
+ /**
+ * Destroy the NodeView, leaving it in an invalid state.
+ */
  destroy(): void;
  /**
  * Ensure focus on the inner editor whenever this node has focus.
@@ -87,7 +93,6 @@ declare class MathView implements NodeView, ICursorPosObserver {
  ensureFocus(): void;
  // == Updates ======================================= //
  update(node: ProseNode, decorations: Decoration[]): boolean;
- updateCursorPos(state: EditorState): void;
  // == Events ===================================== //
  selectNode(): void;
  deselectNode(): void;
@@ -97,6 +102,15 @@ declare class MathView implements NodeView, ICursorPosObserver {
  renderMath(): void;
  // == Inner Editor ================================== //
  dispatchInner(tr: Transaction): void;
+ /**
+ * Mark the render pane as active. CSS controls actual visibility.
+ * @param isPreview If TRUE, we are currently in preview mode.
+ */
+ showRender(isPreview: boolean): void;
+ /**
+ * Mark the render pane as inactive. CSS controls actual visibility.
+ */
+ hideRender(): void;
  openEditor(): void;
  /**
  * Called when the inner ProseMirror editor should close.
@@ -211,5 +225,5 @@ declare class ProseMirrorTextSerializer<S extends Schema<any, any>> {
  serializeNode(node: ProseNode<S>): string | null;
 }
 declare const mathSerializer: ProseMirrorTextSerializer<Schema<"text" | "doc" | "paragraph" | "math_inline" | "math_display", "math_select">>;
-export { MathView, ICursorPosObserver, mathPlugin, createMathView, IMathPluginState, mathSchemaSpec, createMathSchema, mathBackspaceCmd, makeBlockMathInputRule, makeInlineMathInputRule, REGEX_BLOCK_MATH_DOLLARS, REGEX_INLINE_MATH_DOLLARS, REGEX_INLINE_MATH_DOLLARS_ESCAPED, mathSelectPlugin, insertMathCmd, mathSerializer, SchemaSpecNodeT, SchemaSpecMarkT, SchemaNodeT, SchemaMarkT };
+export { MathView, mathPlugin, createMathView, IMathPluginState, mathSchemaSpec, createMathSchema, mathBackspaceCmd, makeBlockMathInputRule, makeInlineMathInputRule, REGEX_BLOCK_MATH_DOLLARS, REGEX_INLINE_MATH_DOLLARS, REGEX_INLINE_MATH_DOLLARS_ESCAPED, mathSelectPlugin, insertMathCmd, mathSerializer, SchemaSpecNodeT, SchemaSpecMarkT, SchemaNodeT, SchemaMarkT };
 //# sourceMappingURL=index.es.d.ts.map