feat(bundle): add changePreviewVisible method to editor api (#1153)

ReFFaT · web-flow · commit 2d5a7bbf0bbe · 2026-06-29T12:11:36.000+03:00
diff --git a/demo/src/components/Playground.tsx b/demo/src/components/Playground.tsx
@@ -154,6 +154,7 @@ export const Playground = memo<PlaygroundProps>((props) => {
         yfmMods,
     } = props;
     const [editorMode, setEditorMode] = useState<MarkdownEditorMode>(initialEditor ?? 'wysiwyg');
+    const [previewVisible, setPreviewVisible] = useState(false);
     const [mdRaw, setMdRaw] = useState<MarkupString>(initial || '');
 
     useEffect(() => {
@@ -352,6 +353,10 @@ export const Playground = memo<PlaygroundProps>((props) => {
         function onChangeToolbarVisibility({visible}: {visible: boolean}) {
             console.info('Toolbar visible: ' + visible);
         }
+        function onChangePreviewVisible({visible}: {visible: boolean}) {
+            setPreviewVisible(visible);
+            console.info(`Preview visible: ${visible}`);
+        }
 
         mdEditor.on('cancel', onCancel);
         mdEditor.on('submit', onSubmit);
@@ -360,6 +365,7 @@ export const Playground = memo<PlaygroundProps>((props) => {
         mdEditor.on('change-editor-mode', onChangeEditorType);
         mdEditor.on('change-split-mode-enabled', onChangeSplitModeEnabled);
         mdEditor.on('change-toolbar-visibility', onChangeToolbarVisibility);
+        mdEditor.on('change-preview-visible', onChangePreviewVisible);
 
         return () => {
             mdEditor.off('cancel', onCancel);
@@ -369,6 +375,7 @@ export const Playground = memo<PlaygroundProps>((props) => {
             mdEditor.off('change-editor-mode', onChangeEditorType);
             mdEditor.off('change-split-mode-enabled', onChangeSplitModeEnabled);
             mdEditor.off('change-toolbar-visibility', onChangeToolbarVisibility);
+            mdEditor.off('change-preview-visible', onChangePreviewVisible);
         };
     }, [mdEditor]);
 
@@ -466,6 +473,14 @@ export const Playground = memo<PlaygroundProps>((props) => {
                                 mdEditor.focus();
                             }}
                         />
+                        {editorMode === 'markup' && (
+                            <DropdownMenu.Item
+                                text={`Toggle Preview (${previewVisible ? 'on' : 'off'})`}
+                                action={() => {
+                                    mdEditor.changePreviewVisible();
+                                }}
+                            />
+                        )}
                     </DropdownMenu>
                     {mdEditor.currentMode === 'markup' && (
                         <MoveToLine
diff --git a/packages/editor/src/bundle/Editor.test.ts b/packages/editor/src/bundle/Editor.test.ts
@@ -0,0 +1,131 @@
+/// <reference types="jest" />
+import {ReactRenderStorage} from '../extensions';
+import {Logger2} from '../logger';
+import {DirectiveSyntaxContext} from '../utils/directive';
+
+import {EditorImpl} from './Editor';
+
+function createEditor(overrides: Partial<ConstructorParameters<typeof EditorImpl>[0]> = {}) {
+    return new EditorImpl({
+        logger: new Logger2(),
+        renderStorage: new ReactRenderStorage(),
+        preset: 'full',
+        directiveSyntax: new DirectiveSyntaxContext(undefined),
+        pmTransformers: [],
+        ...overrides,
+    });
+}
+
+function createEditorWithPreview(
+    overrides: Partial<ConstructorParameters<typeof EditorImpl>[0]> = {},
+) {
+    return createEditor({
+        markupConfig: {renderPreview: () => null},
+        ...overrides,
+    });
+}
+
+describe('EditorImpl: changePreviewVisible', () => {
+    it('should be a no-op when renderPreview is not configured', () => {
+        const editor = createEditor();
+        const listener = jest.fn();
+        editor.on('change-preview-visible', listener);
+
+        editor.changePreviewVisible(true);
+
+        expect(editor.previewVisible).toBe(false);
+        expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('should show preview and emit change-preview-visible event', () => {
+        const editor = createEditorWithPreview();
+        const listener = jest.fn();
+        editor.on('change-preview-visible', listener);
+
+        editor.changePreviewVisible(true);
+
+        expect(editor.previewVisible).toBe(true);
+        expect(listener).toHaveBeenCalledTimes(1);
+        expect(listener).toHaveBeenCalledWith({visible: true});
+    });
+
+    it('should toggle preview when called without argument', () => {
+        const editor = createEditorWithPreview();
+        const listener = jest.fn();
+        editor.on('change-preview-visible', listener);
+
+        editor.changePreviewVisible(); // false → true
+        expect(editor.previewVisible).toBe(true);
+
+        editor.changePreviewVisible(); // true → false
+        expect(editor.previewVisible).toBe(false);
+
+        expect(listener).toHaveBeenCalledTimes(2);
+        expect(listener).toHaveBeenNthCalledWith(1, {visible: true});
+        expect(listener).toHaveBeenNthCalledWith(2, {visible: false});
+    });
+
+    it('should be a no-op when split mode is enabled', () => {
+        const editor = createEditorWithPreview({
+            initial: {splitModeEnabled: true},
+            markupConfig: {renderPreview: () => null, splitMode: 'vertical'},
+        });
+        const listener = jest.fn();
+        editor.on('change-preview-visible', listener);
+
+        editor.changePreviewVisible(true);
+
+        expect(editor.previewVisible).toBe(false);
+        expect(listener).not.toHaveBeenCalled();
+    });
+});
+
+describe('EditorImpl: changeSplitModeEnabled', () => {
+    it('should enable split mode and emit change-split-mode-enabled event', () => {
+        const editor = createEditor();
+        const listener = jest.fn();
+        editor.on('change-split-mode-enabled', listener);
+
+        editor.changeSplitModeEnabled({splitModeEnabled: true});
+
+        expect(editor.splitModeEnabled).toBe(true);
+        expect(listener).toHaveBeenCalledTimes(1);
+        expect(listener).toHaveBeenCalledWith({splitModeEnabled: true});
+    });
+});
+
+describe('EditorImpl: mutual exclusion between preview and split mode', () => {
+    it('should not show preview when split mode is active (changePreviewVisible is a no-op)', () => {
+        const editor = createEditorWithPreview({
+            initial: {splitModeEnabled: true},
+            markupConfig: {renderPreview: () => null, splitMode: 'vertical'},
+        });
+        const splitListener = jest.fn();
+        editor.on('change-split-mode-enabled', splitListener);
+
+        expect(editor.splitModeEnabled).toBe(true);
+
+        editor.changePreviewVisible(true);
+
+        expect(editor.previewVisible).toBe(false);
+        expect(editor.splitModeEnabled).toBe(true);
+        // split-mode state did not change
+        expect(splitListener).not.toHaveBeenCalled();
+    });
+
+    it('should not emit events when state does not change', () => {
+        const editor = createEditorWithPreview();
+        const previewListener = jest.fn();
+        const splitListener = jest.fn();
+        editor.on('change-preview-visible', previewListener);
+        editor.on('change-split-mode-enabled', splitListener);
+
+        // previewVisible already false
+        editor.changePreviewVisible(false);
+        // splitModeEnabled already false
+        editor.changeSplitModeEnabled({splitModeEnabled: false});
+
+        expect(previewListener).not.toHaveBeenCalled();
+        expect(splitListener).not.toHaveBeenCalled();
+    });
+});
diff --git a/packages/editor/src/bundle/Editor.ts b/packages/editor/src/bundle/Editor.ts
@@ -87,6 +87,10 @@ export interface EditorInt
 
     changeSplitModeEnabled(opts: {splitModeEnabled: boolean}): void;
 
+    readonly previewVisible: boolean;
+
+    changePreviewVisible(visible?: boolean): void;
+
     destroy(): void;
 }
 
@@ -111,6 +115,7 @@ export class EditorImpl extends SafeEventEmitter<EventMapInt> implements EditorI
     #toolbarVisible: boolean;
     #splitModeEnabled: boolean;
     #splitMode: SplitMode;
+    #previewVisible: boolean;
     #renderPreview?: RenderPreview;
     #wysiwygEditor?: WysiwygEditor;
     #markupEditor?: MarkupEditor;
@@ -198,6 +203,10 @@ export class EditorImpl extends SafeEventEmitter<EventMapInt> implements EditorI
         return this.#splitMode;
     }
 
+    get previewVisible(): boolean {
+        return this.#previewVisible;
+    }
+
     get preset(): EditorPreset {
         return this.#preset;
     }
@@ -341,6 +350,7 @@ export class EditorImpl extends SafeEventEmitter<EventMapInt> implements EditorI
         this.#toolbarVisible = initial.toolbarVisible ?? true;
         this.#splitMode = (markupConfig.renderPreview && markupConfig.splitMode) ?? false;
         this.#splitModeEnabled = (this.#splitMode && initial.splitModeEnabled) ?? false;
+        this.#previewVisible = false;
         this.#renderPreview = markupConfig.renderPreview;
 
         this.#markup = initial.markup ?? '';
@@ -433,6 +443,14 @@ export class EditorImpl extends SafeEventEmitter<EventMapInt> implements EditorI
         this.emit('change-split-mode-enabled', opts);
     }
 
+    changePreviewVisible(visible = !this.#previewVisible): void {
+        if (!this.#renderPreview || this.#splitModeEnabled) return;
+        if (this.#previewVisible === visible) return;
+        this.#previewVisible = visible;
+        this.emit('rerender', null);
+        this.emit('change-preview-visible', {visible});
+    }
+
     focus(): void {
         return this.currentEditor.focus();
     }
diff --git a/packages/editor/src/bundle/MarkdownEditorView.tsx b/packages/editor/src/bundle/MarkdownEditorView.tsx
@@ -16,7 +16,7 @@ import type {ClassNameProps} from '../classname';
 import {i18n} from '../i18n/bundle';
 import {globalLogger} from '../logger';
 import type {ToolbarsPreset} from '../modules/toolbars/types';
-import {useBooleanState, useSticky} from '../react-utils';
+import {useSticky} from '../react-utils';
 import {isMac} from '../utils';
 
 import type {Editor, EditorInt} from './Editor';
@@ -41,9 +41,6 @@ interface EditorWrapperProps extends QAProps, ToolbarConfigs, Omit<ViewProps, 'e
     editor: EditorInt;
     editorMode: MarkdownEditorMode;
     isFocused: boolean;
-    showPreview: boolean;
-    toggleShowPreview: () => void;
-    unsetShowPreview: () => void;
 }
 const EditorWrapper = forwardRef<HTMLDivElement, EditorWrapperProps>(
     (
@@ -58,16 +55,14 @@ const EditorWrapper = forwardRef<HTMLDivElement, EditorWrapperProps>(
             markupToolbarConfig: initialMarkupToolbarConfig,
             qa,
             settingsVisible: settingsVisibleProp,
-            showPreview,
             stickyToolbar,
-            toggleShowPreview,
             toolbarsPreset,
-            unsetShowPreview,
             wysiwygHiddenActionsConfig: initialWysiwygHiddenActionsConfig,
             wysiwygToolbarConfig: initialWysiwygToolbarConfig,
         },
         ref,
     ) => {
+        const showPreview = editor.previewVisible;
         const {
             wysiwygToolbarConfig,
             markupToolbarConfig,
@@ -97,9 +92,9 @@ const EditorWrapper = forwardRef<HTMLDivElement, EditorWrapperProps>(
         const onModeChange = useCallback(
             (type: MarkdownEditorMode) => {
                 editor.changeEditorMode({mode: type, reason: 'settings'});
-                unsetShowPreview();
+                editor.changePreviewVisible(false);
             },
-            [editor, unsetShowPreview],
+            [editor],
         );
         const onToolbarVisibilityChange = useCallback(
             (visible: boolean) => {
@@ -109,17 +104,15 @@ const EditorWrapper = forwardRef<HTMLDivElement, EditorWrapperProps>(
         );
         const onSplitModeChange = useCallback(
             (splitModeEnabled: boolean) => {
-                unsetShowPreview();
                 editor.changeSplitModeEnabled({splitModeEnabled});
             },
-            [editor, unsetShowPreview],
+            [editor],
         );
         const onShowPreviewChange = useCallback(
             (showPreviewValue: boolean) => {
-                editor.changeSplitModeEnabled({splitModeEnabled: false});
-                if (showPreviewValue !== showPreview) toggleShowPreview();
+                editor.changePreviewVisible(showPreviewValue);
             },
-            [editor, showPreview, toggleShowPreview],
+            [editor],
         );
         const canRenderPreview = Boolean(
             editor.renderPreview && editorMode === 'markup' && !editor.splitModeEnabled,
@@ -129,10 +122,10 @@ const EditorWrapper = forwardRef<HTMLDivElement, EditorWrapperProps>(
             (e) => canRenderPreview && isPreviewKeyDown(e),
             (e) => {
                 e.preventDefault();
-                onShowPreviewChange(!showPreview);
+                editor.changePreviewVisible();
             },
             {event: 'keydown'},
-            [showPreview, editorMode, onShowPreviewChange, canRenderPreview],
+            [editorMode, editor, canRenderPreview],
         );
 
         useKey(
@@ -141,11 +134,11 @@ const EditorWrapper = forwardRef<HTMLDivElement, EditorWrapperProps>(
                 editor.emit('submit', null);
 
                 if (hidePreviewAfterSubmit) {
-                    onShowPreviewChange(false);
+                    editor.changePreviewVisible(false);
                 }
             },
             {event: 'keydown'},
-            [hidePreviewAfterSubmit, enableSubmitInPreview, showPreview, showPreview],
+            [hidePreviewAfterSubmit, enableSubmitInPreview, showPreview, editor],
         );
 
         const settingsProps = {
@@ -262,7 +255,6 @@ export const MarkdownEditorView = forwardRef<HTMLDivElement, MarkdownEditorViewP
     (props, ref) => {
         const divRef = useEnsuredForwardedRef(ref as React.MutableRefObject<HTMLDivElement>);
         const editorWrapperRef = useRef(null);
-        const [showPreview, , unsetShowPreview, toggleShowPreview] = useBooleanState(false);
 
         const [isMounted, setIsMounted] = useState(false);
         useEffect(() => {
@@ -308,10 +300,10 @@ export const MarkdownEditorView = forwardRef<HTMLDivElement, MarkdownEditorViewP
         const toaster = useToaster();
 
         useEffect(() => {
-            if (showPreview) {
+            if (editor.previewVisible) {
                 divRef.current.focus();
             }
-        }, [divRef, showPreview]);
+        }, [divRef, editor, editor.previewVisible]);
 
         const areSettingsVisible =
             settingsVisible === true ||
@@ -366,11 +358,8 @@ export const MarkdownEditorView = forwardRef<HTMLDivElement, MarkdownEditorViewP
                         qa="g-md-editor-mode"
                         ref={editorWrapperRef}
                         settingsVisible={settingsVisible}
-                        showPreview={showPreview}
                         stickyToolbar={stickyToolbar}
-                        toggleShowPreview={toggleShowPreview}
                         toolbarsPreset={toolbarsPreset}
-                        unsetShowPreview={unsetShowPreview}
                         wysiwygHiddenActionsConfig={wysiwygHiddenActionsConfig}
                         wysiwygToolbarConfig={wysiwygToolbarConfig}
                     />
diff --git a/packages/editor/src/bundle/editor-public-types.ts b/packages/editor/src/bundle/editor-public-types.ts
@@ -17,9 +17,17 @@ export interface MarkdownEditorInstance extends Receiver<EventMap>, CommonEditor
     readonly logger: Logger2.LogReceiver;
     readonly currentMode: MarkdownEditorMode;
     readonly toolbarVisible: boolean;
+    /** Whether the full-screen markup preview is currently visible. */
+    readonly previewVisible: boolean;
     setEditorMode(mode: MarkdownEditorMode, opts?: Pick<ChangeEditorModeOptions, 'emit'>): void;
     moveCursor(position: 'start' | 'end' | {line: number}): void;
     insert(markup: MarkupString): void;
+    /**
+     * Control the full-screen markup preview.
+     * Pass `true`/`false` to explicitly show/hide it, or call with no argument to toggle.
+     * No-op if `renderPreview` is not configured or split mode is currently enabled.
+     */
+    changePreviewVisible(visible?: boolean): void;
     /** @internal used in demo for dev-tools */
     readonly _wysiwygView?: PMEditorView;
 }
diff --git a/packages/editor/src/bundle/events.ts b/packages/editor/src/bundle/events.ts
@@ -16,4 +16,5 @@ export interface EventMap {
     'change-editor-mode': {mode: MarkdownEditorMode};
     'change-toolbar-visibility': {visible: boolean};
     'change-split-mode-enabled': {splitModeEnabled: boolean};
+    'change-preview-visible': {visible: boolean};
 }

Original file line number	Diff line number	Diff line change
`@@ -16,4 +16,5 @@ export interface EventMap {`
`16`	`16`	`'change-editor-mode': {mode: MarkdownEditorMode};`
`17`	`17`	`'change-toolbar-visibility': {visible: boolean};`
`18`	`18`	`'change-split-mode-enabled': {splitModeEnabled: boolean};`
	`19`	`+ 'change-preview-visible': {visible: boolean};`
`19`	`20`	`}`