feat(Math)!: add math hints

Author: d3m1d0v

src/extensions/yfm/Math/hint.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import {createPortal} from 'react-dom';
+import {HelpPopover, HelpPopoverProps, Link} from '@gravity-ui/uikit';
+
+import {cn} from '../../../classname';
+import {i18n} from '../../../i18n/math-hint';
+
+export const b = cn('MathHint');
+
+const MathHintContent: React.FC = function MathHintContent() {
+    return (
+        <>
+            {i18n('math_hint')}{' '}
+            <Link href={'https://katex.org/'} target={'blank'}>
+                {i18n('math_hint_katex')}
+            </Link>
+        </>
+    );
+};
+
+type MathHintProps = Pick<HelpPopoverProps, 'offset' | 'hasArrow'>;
+
+const MathHint: React.FC<MathHintProps> = function MathHint(props) {
+    return (
+        <HelpPopover
+            placement={['bottom-end', 'top-end']}
+            {...props}
+            content={<MathHintContent />}
+        />
+    );
+};
+
+export function renderMathHint(props: MathHintProps, container: Element): React.ReactNode {
+    return createPortal(<MathHint {...props} />, container);
+}

src/extensions/yfm/Math/index.ts

@@ -37,14 +37,18 @@ export const Math: ExtensionAuto = (builder) => {
         ),
     }));
 
-    builder.addPlugin(mathViewAndEditPlugin).addInputRules((deps) => ({
-        rules: [
-            textblockTypeInputRule(/^\$\$\s$/, mathBType(deps.schema)),
-            inlineNodeInputRule(/\$[^$\s]+\$$/, (match) =>
-                mathIType(deps.schema).create(null, deps.schema.text(match.replace(/\$/g, ''))),
-            ),
-        ],
-    }));
+    builder
+        .addPlugin(() =>
+            mathViewAndEditPlugin({reactRenderer: builder.context.get('reactrenderer')!}),
+        )
+        .addInputRules((deps) => ({
+            rules: [
+                textblockTypeInputRule(/^\$\$\s$/, mathBType(deps.schema)),
+                inlineNodeInputRule(/\$[^$\s]+\$$/, (match) =>
+                    mathIType(deps.schema).create(null, deps.schema.text(match.replace(/\$/g, ''))),
+                ),
+            ],
+        }));
     builder
         .addAction(mathIAction, (deps) => {
             const type = mathIType(deps.schema);

src/extensions/yfm/Math/view-and-edit.scss

@@ -41,4 +41,26 @@
 
         opacity: 0;
     }
+
+    .ye-MathHint {
+        &__block-view {
+            display: none;
+        }
+
+        &__inline-view {
+            display: none;
+        }
+    }
+}
+
+.ye-MathHint {
+    &__block-view {
+        float: right;
+    }
+
+    &__inline-view {
+        display: inline-block;
+
+        margin-right: 6px;
+    }
 }

src/extensions/yfm/Math/view-and-edit.ts

@@ -4,29 +4,42 @@ import type {Node} from 'prosemirror-model';
 import {keydownHandler} from 'prosemirror-keymap';
 import {Decoration, DecorationSet, NodeView} from 'prosemirror-view';
 import {isTextSelection} from '../../../utils/selection';
+import type {ReactRenderer, RendererItem} from '../../../extensions/behavior/ReactRenderer';
 import {moveCursorToEndOfMathInline} from './commands';
 import {CLASSNAMES, MathNode} from './const';
+import {b, renderMathHint} from './hint';
 
 import 'katex/dist/katex.min.css';
 import './view-and-edit.scss';
 
 export abstract class MathNodeView implements NodeView {
     dom: HTMLElement;
     contentDOM: HTMLElement;
+
     protected node: Node;
     protected texContent: string;
     protected mathViewDOM: HTMLElement;
+    protected mathHintContainerDOM: HTMLElement;
+
+    protected hintRendererItem: RendererItem;
+    protected readonly reactRenderer: ReactRenderer;
 
-    abstract createDOM(): Record<'dom' | 'contentDOM' | 'mathViewDOM', HTMLElement>;
+    abstract createDOM(): Record<
+        'dom' | 'contentDOM' | 'mathViewDOM' | 'mathHintContainerDOM',
+        HTMLElement
+    > & {hintRendererItem: RendererItem};
     abstract isDisplayMode(): boolean;
 
-    constructor(node: Node) {
+    constructor(node: Node, reactRenderer: ReactRenderer) {
         this.node = node;
+        this.reactRenderer = reactRenderer;
         this.texContent = this.getTexContent();
         const elems = this.createDOM();
         this.dom = elems.dom;
         this.contentDOM = elems.contentDOM;
         this.mathViewDOM = elems.mathViewDOM;
+        this.mathHintContainerDOM = elems.mathHintContainerDOM;
+        this.hintRendererItem = elems.hintRendererItem;
         this.renderKatex();
     }
 
@@ -41,6 +54,14 @@ export abstract class MathNodeView implements NodeView {
         return true;
     }
 
+    ignoreMutation(mutation: MutationRecord): boolean {
+        return mutation.type === 'childList' && mutation.target === this.mathHintContainerDOM;
+    }
+
+    destroy() {
+        this.hintRendererItem.remove();
+    }
+
     protected renderKatex() {
         try {
             katex.render(this.texContent, this.mathViewDOM, {
@@ -62,11 +83,15 @@ export abstract class MathNodeView implements NodeView {
 }
 
 export class MathInlineNodeView extends MathNodeView {
+    destroy() {
+        this.hintRendererItem?.remove();
+    }
+
     isDisplayMode(): boolean {
         return false;
     }
 
-    createDOM(): Record<'dom' | 'contentDOM' | 'mathViewDOM', HTMLElement> {
+    createDOM() {
         const dom = document.createElement('span');
         dom.classList.add('math-container', 'math-inline-container');
 
@@ -76,10 +101,25 @@ export class MathInlineNodeView extends MathNodeView {
 
         const mathInlineDOM = this.createMathInlineDOM();
 
+        const mathHintContainerDOM = document.createElement('div');
+        mathHintContainerDOM.contentEditable = 'false';
+        mathHintContainerDOM.classList.add(b('inline-view'));
+
         dom.appendChild(mathViewDOM);
         dom.appendChild(mathInlineDOM.container);
-
-        return {dom, contentDOM: mathInlineDOM.content, mathViewDOM};
+        dom.appendChild(mathHintContainerDOM);
+
+        const hintRendererItem = this.reactRenderer.createItem('math-inline-hint', () =>
+            renderMathHint({offset: {left: 3, top: -1}}, mathHintContainerDOM),
+        );
+
+        return {
+            dom,
+            contentDOM: mathInlineDOM.content,
+            mathViewDOM,
+            mathHintContainerDOM,
+            hintRendererItem,
+        };
     }
 
     // same as math-inline spec toDOM()
@@ -108,7 +148,7 @@ export class MathBlockNodeView extends MathNodeView {
         return true;
     }
 
-    createDOM(): Record<'dom' | 'contentDOM' | 'mathViewDOM', HTMLElement> {
+    createDOM() {
         const dom = document.createElement('div');
         dom.classList.add('math-container', 'math-block-container');
 
@@ -119,19 +159,28 @@ export class MathBlockNodeView extends MathNodeView {
         const contentDOM = document.createElement('div');
         contentDOM.classList.add('math-block');
 
+        const mathHintContainerDOM = document.createElement('div');
+        mathHintContainerDOM.contentEditable = 'false';
+        mathHintContainerDOM.classList.add(b('block-view'));
+
+        dom.appendChild(mathHintContainerDOM);
         dom.appendChild(mathViewDOM);
         dom.appendChild(contentDOM);
 
-        return {dom, contentDOM, mathViewDOM};
+        const hintRendererItem = this.reactRenderer.createItem('math-block-hint', () =>
+            renderMathHint({offset: {left: -3}}, mathHintContainerDOM),
+        );
+
+        return {dom, contentDOM, mathViewDOM, mathHintContainerDOM, hintRendererItem};
     }
 }
 
-export const mathViewAndEditPlugin = () =>
+export const mathViewAndEditPlugin = ({reactRenderer}: {reactRenderer: ReactRenderer}) =>
     new Plugin({
         props: {
             nodeViews: {
-                [MathNode.Block]: (node) => new MathBlockNodeView(node),
-                [MathNode.Inline]: (node) => new MathInlineNodeView(node),
+                [MathNode.Block]: (node) => new MathBlockNodeView(node, reactRenderer),
+                [MathNode.Inline]: (node) => new MathInlineNodeView(node, reactRenderer),
             },
             handleKeyDown: keydownHandler({
                 ArrowLeft: moveCursorToEndOfMathInline,

src/i18n/math-hint/en.json

@@ -0,0 +1,4 @@
+{
+  "math_hint": "Math uses",
+  "math_hint_katex": "Katex syntax"
+}

src/i18n/math-hint/index.ts

@@ -0,0 +1,8 @@
+import {registerKeyset} from '../i18n';
+
+import en from './en.json';
+import ru from './ru.json';
+
+const KEYSET = 'math-hint';
+
+export const i18n = registerKeyset(KEYSET, {en, ru});

src/i18n/math-hint/ru.json

@@ -0,0 +1,4 @@
+{
+  "math_hint": "При создании формул используется",
+  "math_hint_katex": "синтаксис Katex"
+}