feat: add directiveSyntax experiment

Author: d3m1d0v

demo/components/Playground.tsx

@@ -5,8 +5,9 @@ import {Button, DropdownMenu} from '@gravity-ui/uikit';
 import {toaster} from '@gravity-ui/uikit/toaster-singleton-react-18';
 
 import {
+    type DirectiveSyntaxValue,
     type EscapeConfig,
-    FileUploadHandler,
+    type FileUploadHandler,
     type MarkdownEditorMode,
     MarkdownEditorView,
     type MarkdownEditorViewProps,
@@ -21,16 +22,16 @@ import {
     wysiwygToolbarConfigs,
 } from '../../src';
 import type {ToolbarActionData} from '../../src/bundle/Editor';
-import {Extension} from '../../src/cm/state';
+import type {Extension} from '../../src/cm/state';
 import {FoldingHeading} from '../../src/extensions/additional/FoldingHeading';
 import {Math} from '../../src/extensions/additional/Math';
 import {Mermaid} from '../../src/extensions/additional/Mermaid';
 import {YfmHtmlBlock} from '../../src/extensions/additional/YfmHtmlBlock';
 import {getSanitizeYfmHtmlBlock} from '../../src/extensions/additional/YfmHtmlBlock/utils';
 import {cloneDeep} from '../../src/lodash';
-import {CodeEditor} from '../../src/markup';
+import type {CodeEditor} from '../../src/markup';
 import {VERSION} from '../../src/version';
-import {plugins} from '../defaults/md-plugins';
+import {getPlugins} from '../defaults/md-plugins';
 import useYfmHtmlBlockStyles from '../hooks/useYfmHtmlBlockStyles';
 import {block} from '../utils/cn';
 import {randomDelay} from '../utils/delay';
@@ -91,6 +92,7 @@ export type PlaygroundProps = {
     markupToolbarConfig?: ToolbarGroupData<CodeEditor>[];
     onChangeEditorType?: (mode: MarkdownEditorMode) => void;
     onChangeSplitModeEnabled?: (splitModeEnabled: boolean) => void;
+    directiveSyntax?: DirectiveSyntaxValue;
 } & Pick<
     UseMarkdownEditorProps,
     | 'needToSetDimensionsForUploadedImages'
@@ -142,6 +144,7 @@ export const Playground = React.memo<PlaygroundProps>((props) => {
         hidePreviewAfterSubmit,
         needToSetDimensionsForUploadedImages,
         experimental,
+        directiveSyntax,
     } = props;
     const [editorMode, setEditorMode] = React.useState<MarkdownEditorMode>(
         initialEditor ?? 'wysiwyg',
@@ -153,15 +156,15 @@ export const Playground = React.memo<PlaygroundProps>((props) => {
     }, [mdRaw]);
 
     const renderPreview = useCallback<RenderPreview>(
-        ({getValue, md}) => (
+        ({getValue, md, directiveSyntax}) => (
             <SplitModePreview
                 getValue={getValue}
                 allowHTML={md.html}
                 linkify={md.linkify}
                 linkifyTlds={md.linkifyTlds}
                 breaks={md.breaks}
                 needToSanitizeHtml={sanitizeHtml}
-                plugins={plugins}
+                plugins={getPlugins({directiveSyntax})}
             />
         ),
         [sanitizeHtml],
@@ -182,7 +185,10 @@ export const Playground = React.memo<PlaygroundProps>((props) => {
             needToSetDimensionsForUploadedImages,
             renderPreview: renderPreviewDefined ? renderPreview : undefined,
             fileUploadHandler,
-            experimental,
+            experimental: {
+                ...experimental,
+                directiveSyntax,
+            },
             prepareRawMarkup: prepareRawMarkup
                 ? (value) => '**prepare raw markup**\n\n' + value
                 : undefined,
@@ -249,6 +255,7 @@ export const Playground = React.memo<PlaygroundProps>((props) => {
             experimental?.needToSetDimensionsForUploadedImages,
             experimental?.beforeEditorModeChange,
             experimental?.prepareRawMarkup,
+            directiveSyntax,
         ],
     );
 

demo/components/PlaygroundMini.tsx

@@ -23,6 +23,7 @@ export type PlaygroundMiniProps = Pick<
     | 'onChangeEditorType'
     | 'onChangeSplitModeEnabled'
     | 'escapeConfig'
+    | 'directiveSyntax'
 > & {withDefaultInitialContent?: boolean};
 
 export const PlaygroundMini = React.memo<PlaygroundMiniProps>(

demo/defaults/args.ts

@@ -16,4 +16,5 @@ export const args: Meta<PlaygroundMiniProps>['args'] = {
     initialSplitModeEnabled: false,
     renderPreviewDefined: true,
     height: 'initial',
+    directiveSyntax: 'disabled',
 };

demo/defaults/md-plugins.ts

@@ -19,6 +19,7 @@ import yfmTable from '@diplodoc/transform/lib/plugins/table';
 import video from '@diplodoc/transform/lib/plugins/video';
 import type {PluginWithParams} from 'markdown-it/lib';
 
+import type {RenderPreviewParams} from '../../src';
 import {emojiDefs} from '../../src/bundle/emoji';
 import color from '../../src/markdown-it/color';
 import {bare as emoji} from '../../src/markdown-it/emoji';
@@ -30,54 +31,62 @@ export const LATEX_RUNTIME = 'extension:latex';
 export const MERMAID_RUNTIME = 'extension:mermaid';
 export const YFM_HTML_BLOCK_RUNTIME = 'extension:yfm-html-block';
 
-const defaultPlugins: PluginWithParams[] = [
-    anchors,
-    code,
-    yfmCut({bundle: false}) as PluginWithParams,
-    deflist,
-    file,
-    (md) => md.use(imsize, {enableInlineStyling: true}),
-    meta,
-    monospace,
-    notes,
-    sup,
-    yfmTabs({
-        bundle: false,
-        features: {
-            enabledVariants: {
-                regular: true,
-                radio: true,
-                dropdown: false,
-                accordion: false,
+type GetPluginsOptions = {
+    directiveSyntax?: RenderPreviewParams['directiveSyntax'];
+};
+
+export function getPlugins(_opts: GetPluginsOptions = {}): markdownit.PluginWithParams[] {
+    const defaultPlugins: PluginWithParams[] = [
+        anchors,
+        code,
+        yfmCut({bundle: false}),
+        deflist,
+        file,
+        (md) => md.use(imsize, {enableInlineStyling: true}),
+        meta,
+        monospace,
+        notes,
+        sup,
+        yfmTabs({
+            bundle: false,
+            features: {
+                enabledVariants: {
+                    regular: true,
+                    radio: true,
+                    dropdown: false,
+                    accordion: false,
+                },
             },
-        },
-    }),
-    video,
-    yfmTable,
-];
-const extendedPlugins = defaultPlugins.concat(
-    (md) => md.use(emoji, {defs: emojiDefs}),
-    checkbox,
-    color,
-    ins,
-    latex({bundle: false, validate: false, runtime: LATEX_RUNTIME}),
-    mark,
-    mermaid({bundle: false, runtime: MERMAID_RUNTIME}),
-    sub,
-    yfmHtmlBlock({
-        bundle: false,
-        runtimeJsPath: YFM_HTML_BLOCK_RUNTIME,
-        head: `
-            <base target="_blank" />
-            <style>
-                html, body {
-                    margin: 0;
-                    padding: 0;
-                }
-            </style
-        `,
-    }),
-    foldingHeadings({bundle: false}),
-);
+        }),
+        video,
+        yfmTable,
+    ];
+    const extendedPlugins = defaultPlugins.concat(
+        (md) => md.use(emoji, {defs: emojiDefs}),
+        checkbox,
+        color,
+        ins,
+        latex({bundle: false, validate: false, runtime: LATEX_RUNTIME}),
+        mark,
+        mermaid({bundle: false, runtime: MERMAID_RUNTIME}),
+        sub,
+        yfmHtmlBlock({
+            bundle: false,
+            runtimeJsPath: YFM_HTML_BLOCK_RUNTIME,
+            head: `
+                        <base target="_blank" />
+                        <style>
+                            html, body {
+                                margin: 0;
+                                padding: 0;
+                            }
+                        </style
+                    `,
+        }),
+        foldingHeadings({bundle: false}),
+    );
+
+    return extendedPlugins;
+}
 
-export {extendedPlugins as plugins};
+export const plugins = getPlugins();

demo/stories/markdown/Markdown.stories.tsx

@@ -61,7 +61,7 @@ export default {
     args: args,
     parameters: {
         controls: {
-            exclude: excludedControls,
+            exclude: excludedControls.concat('directiveSyntax'),
         },
     },
 };

src/bundle/Editor.ts

@@ -17,6 +17,7 @@ import {logger} from '../logger';
 import {createCodemirror} from '../markup';
 import {type CodeEditor, Editor as MarkupEditor} from '../markup/editor';
 import {type Emitter, FileUploadHandler, type Receiver, SafeEventEmitter} from '../utils';
+import type {DirectiveSyntaxContext} from '../utils/directive';
 
 import type {
     MarkdownEditorMode as EditorMode,
@@ -79,6 +80,7 @@ export interface EditorInt
     readonly splitMode: SplitMode;
     readonly preset: EditorPreset;
     readonly mdOptions: Readonly<MarkdownEditorMdOptions>;
+    readonly directiveSyntax: DirectiveSyntaxContext;
 
     /** @internal used in demo for dev-tools */
     readonly _wysiwygView?: PMEditorView;
@@ -120,6 +122,7 @@ export type EditorOptions = Pick<
 > & {
     renderStorage: ReactRenderStorage;
     preset: EditorPreset;
+    directiveSyntax: DirectiveSyntaxContext;
 };
 
 /** @internal */
@@ -143,6 +146,7 @@ export class EditorImpl extends SafeEventEmitter<EventMapInt> implements EditorI
     #parseInsertedUrlAsImage?: ParseInsertedUrlAsImage;
     #needToSetDimensionsForUploadedImages: boolean;
     #enableNewImageSizeCalculation: boolean;
+    #directiveSyntax: DirectiveSyntaxContext;
     #prepareRawMarkup?: (value: MarkupString) => MarkupString;
     #beforeEditorModeChange?: (
         options: Pick<ChangeEditorModeOptions, 'mode' | 'reason'>,
@@ -215,6 +219,10 @@ export class EditorImpl extends SafeEventEmitter<EventMapInt> implements EditorI
         return this.#mdOptions;
     }
 
+    get directiveSyntax(): DirectiveSyntaxContext {
+        return this.#directiveSyntax;
+    }
+
     get renderPreview(): RenderPreview | undefined {
         return this.#renderPreview;
     }
@@ -271,6 +279,7 @@ export class EditorImpl extends SafeEventEmitter<EventMapInt> implements EditorI
                     keymaps: this.#markupConfig.keymaps,
                     yfmLangOptions: {languageData: this.#markupConfig.languageData},
                     autocompletion: this.#markupConfig.autocompletion,
+                    directiveSyntax: this.directiveSyntax,
                     receiver: this,
                 }),
             );
@@ -329,6 +338,7 @@ export class EditorImpl extends SafeEventEmitter<EventMapInt> implements EditorI
         this.#needToSetDimensionsForUploadedImages = Boolean(
             experimental.needToSetDimensionsForUploadedImages,
         );
+        this.#directiveSyntax = opts.directiveSyntax;
         this.#enableNewImageSizeCalculation = Boolean(experimental.enableNewImageSizeCalculation);
         this.#prepareRawMarkup = experimental.prepareRawMarkup;
         this.#escapeConfig = wysiwygConfig.escapeConfig;

src/bundle/MarkdownEditorView.tsx

@@ -240,6 +240,7 @@ export const MarkdownEditorView = React.forwardRef<HTMLDivElement, MarkdownEdito
                                             getValue: editor.getValue,
                                             mode: 'preview',
                                             md: editor.mdOptions,
+                                            directiveSyntax: editor.directiveSyntax,
                                         })}
                                     </div>
                                     {settings}

src/bundle/SplitModeView.tsx

@@ -110,6 +110,7 @@ const SplitModeView = React.forwardRef<HTMLDivElement, SplitModeProps>(({editor}
                 getValue: editor.getValue,
                 mode: 'split',
                 md: editor.mdOptions,
+                directiveSyntax: editor.directiveSyntax,
             })}
         </div>
     );

src/bundle/types.ts

@@ -6,6 +6,7 @@ import type {MarkupString} from '../common';
 import type {EscapeConfig, Extension} from '../core';
 import type {CreateCodemirrorParams, YfmLangOptions} from '../markup';
 import type {FileUploadHandler} from '../utils';
+import type {DirectiveSyntaxContext, DirectiveSyntaxOption} from '../utils/directive';
 
 import type {ChangeEditorModeOptions} from './Editor';
 import type {ExtensionsOptions as WysiwygPresetExtensionsOptions} from './wysiwyg-preset';
@@ -19,6 +20,7 @@ export type RenderPreviewParams = {
     getValue: () => MarkupString;
     mode: 'preview' | 'split';
     md: Readonly<MarkdownEditorMdOptions>;
+    directiveSyntax: Pick<DirectiveSyntaxContext, 'option' | 'valueFor' | 'mdPluginValueFor'>;
 };
 export type RenderPreview = (params: RenderPreviewParams) => ReactNode;
 
@@ -71,6 +73,26 @@ export type MarkdownEditorExperimentalOptions = {
     beforeEditorModeChange?: (
         options: Pick<ChangeEditorModeOptions, 'mode' | 'reason'>,
     ) => boolean | undefined;
+    /**
+     * Enables support of directive syntax for diplodoc (YFM) extensions.
+     *
+     * **Note:** This setting affects parsing of markdown markup and serializing to markdown markup.
+     * Be careful with it and use it in consistency with diplodoc/transform and diplodoc-extensions.
+     *
+     * Before enabling this option, make sure that appropriate versions of diplodoc/transform and diplodoc-extensions are installed.
+     *
+     * You can pass an object in `key:value` format to provide different behaviour for each extension individually.
+     *
+     * Values:
+     * - 'disabled' – directive syntax is disabled;
+     * - 'enabled' – directive syntax is enabled. Syntax of existing blocks is preserved. New blocks will be serialized using old syntax;
+     * - 'preserve' – directive syntax is enabled. Syntax of existing blocks is preserved. New blocks will be serialized using directive syntax;
+     * - 'overwrite' – existing blocks will be overwritten using directive syntax through serialization;
+     * - 'only' – old syntax is disabled, only directive syntax available. Blocks in old syntax will not be parsed.
+     *
+     * Default value is 'disabled'.
+     */
+    directiveSyntax?: DirectiveSyntaxOption;
 };
 
 export type MarkdownEditorMarkupConfig = {

src/bundle/useMarkdownEditor.ts

@@ -3,6 +3,7 @@ import {useLayoutEffect, useMemo} from 'react';
 import type {Extension} from '../core';
 import {ReactRenderStorage} from '../extensions';
 import {logger} from '../logger';
+import {DirectiveSyntaxContext} from '../utils/directive';
 
 import {EditorImpl, type EditorInt} from './Editor';
 import type {
@@ -40,11 +41,14 @@ export function useMarkdownEditor<T extends object = {}>(
             props.needToSetDimensionsForUploadedImages;
         const enableNewImageSizeCalculation = experimental.enableNewImageSizeCalculation;
 
+        const directiveSyntax = new DirectiveSyntaxContext(experimental.directiveSyntax);
+
         const extensions: Extension = (builder) => {
             const extensionOptions = wysiwygConfig.extensionOptions ?? props.extensionOptions;
 
             builder.use(BundlePreset, {
                 ...extensionOptions,
+                directiveSyntax,
                 preset,
                 reactRenderer: renderStorage,
                 onCancel: () => {
@@ -71,6 +75,7 @@ export function useMarkdownEditor<T extends object = {}>(
             ...props,
             preset,
             renderStorage,
+            directiveSyntax,
             md: {
                 ...md,
                 breaks,