feat(YfmHtmlBlock): add HTML templates button

Add a templates button inside the YfmHtmlBlock node that opens a popup
with a searchable list of templates and an "add" action.

- templates are merged from plugin options and localStorage (localStorage
  overrides by id); adding writes only to localStorage, never to markup
- the add form accepts several <template id title> blocks at once
- selecting a template overwrites the block srcdoc
- new `templates` plugin option: { items, showButton, allowAdd }

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: makhnatkin

demo/src/components/Playground.tsx

@@ -37,6 +37,7 @@ import {YfmPageConstructorExtension} from '@gravity-ui/markdown-editor-page-cons
 import {wYfmPageConstructorItemData} from '@gravity-ui/markdown-editor-page-constructor-extension/configs';
 import {Button, DropdownMenu} from '@gravity-ui/uikit';
 
+import {htmlBlockTemplates} from '../defaults/html-templates';
 import {getPlugins} from '../defaults/md-plugins';
 import {useLogs} from '../hooks/useLogs';
 import useYfmHtmlBlockStyles from '../hooks/useYfmHtmlBlockStyles';
@@ -236,6 +237,11 @@ export const Playground = memo<PlaygroundProps>((props) => {
                                     storyAdditionalControls?.yfmHtmlBlockAutoSaveEnabled ?? true,
                                 delay: storyAdditionalControls?.yfmHtmlBlockAutoSaveDelay ?? 1000,
                             },
+                            templates: {
+                                items: htmlBlockTemplates,
+                                showButton: true,
+                                allowAdd: true,
+                            },
                             head: `
                         <base target="_blank" />
                         <style>

demo/src/defaults/html-templates.ts

@@ -0,0 +1,25 @@
+export const htmlBlockTemplates = [
+    {
+        id: 'callout',
+        title: 'Callout',
+        content: `<div style="padding:16px;border-left:4px solid #2563eb;background:#eff6ff;border-radius:8px;">
+  <strong>Heads up</strong>
+  <p style="margin:8px 0 0;">Replace this text with your message.</p>
+</div>`,
+    },
+    {
+        id: 'two-columns',
+        title: 'Two columns',
+        content: `<div style="display:grid;grid-template-columns:1fr 1fr;gap:16px;">
+  <div style="padding:16px;background:#f8fafc;border-radius:8px;">Left</div>
+  <div style="padding:16px;background:#f8fafc;border-radius:8px;">Right</div>
+</div>`,
+    },
+    {
+        id: 'cta-button',
+        title: 'CTA button',
+        content: `<a href="#" style="display:inline-block;padding:12px 20px;background:#2563eb;color:#fff;border-radius:8px;text-decoration:none;font-weight:600;">
+  Get started
+</a>`,
+    },
+];

packages/editor/src/extensions/additional/YfmHtmlBlock/YfmHtmlBlockNodeView/TemplatesPopup.scss

@@ -0,0 +1,26 @@
+.g-md-yfm-html-block-templates {
+    display: flex;
+    flex-direction: column;
+
+    min-width: 240px;
+    max-width: 360px;
+
+    &__search {
+        padding: 8px 8px 4px;
+    }
+
+    &__editor {
+        display: flex;
+        flex-direction: column;
+
+        gap: 8px;
+        padding: 8px;
+    }
+
+    &__controls {
+        display: flex;
+        justify-content: end;
+
+        gap: 8px;
+    }
+}

packages/editor/src/extensions/additional/YfmHtmlBlock/YfmHtmlBlockNodeView/TemplatesPopup.tsx

@@ -0,0 +1,137 @@
+import {useMemo, useState} from 'react';
+
+import {Plus} from '@gravity-ui/icons';
+import {Button, Icon, Menu, Popup, TextInput} from '@gravity-ui/uikit';
+
+import {cn} from 'src/classname';
+import {TextAreaFixed as TextArea} from 'src/forms/TextInput';
+import {i18n} from 'src/i18n/yfm-html-block';
+
+import {type HtmlTemplate, parseTemplates, saveTemplates} from '../templates';
+
+import {STOP_EVENT_CLASSNAME} from './const';
+
+import './TemplatesPopup.scss';
+
+const b = cn('yfm-html-block-templates');
+const stop = STOP_EVENT_CLASSNAME;
+
+interface TemplatesPopupProps {
+    anchor: HTMLElement | null;
+    open: boolean;
+    templates: HtmlTemplate[];
+    allowAdd: boolean;
+    onClose: () => void;
+    onApply: (template: HtmlTemplate) => void;
+    onAdded: (templates: HtmlTemplate[]) => void;
+}
+
+export const TemplatesPopup: React.FC<TemplatesPopupProps> = ({
+    anchor,
+    open,
+    templates,
+    allowAdd,
+    onClose,
+    onApply,
+    onAdded,
+}) => {
+    const [adding, setAdding] = useState(false);
+    const [input, setInput] = useState('');
+    const [filter, setFilter] = useState('');
+
+    const filtered = useMemo(() => {
+        const query = filter.trim().toLowerCase();
+        if (!query) return templates;
+        return templates.filter((t) => t.title.toLowerCase().includes(query));
+    }, [templates, filter]);
+
+    const close = () => {
+        setAdding(false);
+        setInput('');
+        setFilter('');
+        onClose();
+    };
+
+    const handleSave = () => {
+        const parsed = parseTemplates(input);
+        if (parsed.length) onAdded(saveTemplates(parsed));
+        setInput('');
+        setAdding(false);
+    };
+
+    return (
+        <Popup anchorElement={anchor} open={open} onOpenChange={close} placement="bottom-end">
+            <div className={b(null, [stop])}>
+                {adding ? (
+                    <div className={b('editor')}>
+                        <TextArea
+                            controlProps={{className: stop}}
+                            value={input}
+                            onUpdate={setInput}
+                            placeholder={i18n('templates_input_placeholder')}
+                            minRows={6}
+                            autoFocus
+                        />
+                        <div className={b('controls')}>
+                            <Button view="flat" className={stop} onClick={() => setAdding(false)}>
+                                <span className={stop}>{i18n('cancel')}</span>
+                            </Button>
+                            <Button
+                                view="action"
+                                className={stop}
+                                disabled={!input.trim()}
+                                onClick={handleSave}
+                            >
+                                <span className={stop}>{i18n('save')}</span>
+                            </Button>
+                        </div>
+                    </div>
+                ) : (
+                    <>
+                        {templates.length > 0 && (
+                            <div className={b('search')}>
+                                <TextInput
+                                    className={stop}
+                                    controlProps={{className: stop}}
+                                    size="s"
+                                    value={filter}
+                                    onUpdate={setFilter}
+                                    placeholder={i18n('search_templates')}
+                                    autoFocus
+                                />
+                            </div>
+                        )}
+                        <Menu className={stop}>
+                            {allowAdd && (
+                                <Menu.Item
+                                    className={stop}
+                                    iconStart={<Icon data={Plus} />}
+                                    onClick={() => setAdding(true)}
+                                >
+                                    {i18n('add_template')}
+                                </Menu.Item>
+                            )}
+                            {filtered.map((template) => (
+                                <Menu.Item
+                                    key={template.id}
+                                    className={stop}
+                                    onClick={() => {
+                                        onApply(template);
+                                        close();
+                                    }}
+                                >
+                                    {template.title}
+                                </Menu.Item>
+                            ))}
+                            {filtered.length === 0 && (
+                                <Menu.Item disabled className={stop}>
+                                    {i18n('templates_empty')}
+                                </Menu.Item>
+                            )}
+                        </Menu>
+                    </>
+                )}
+            </div>
+        </Popup>
+    );
+};

packages/editor/src/extensions/additional/YfmHtmlBlock/YfmHtmlBlockNodeView/YfmHtmlBlockView.tsx

@@ -2,28 +2,31 @@ import {useEffect, useMemo, useRef, useState} from 'react';
 
 import {getStyles} from '@diplodoc/html-extension';
 import type {IHTMLIFrameElementConfig} from '@diplodoc/html-extension/runtime';
-import {Ellipsis as DotsIcon, Eye} from '@gravity-ui/icons';
+import {Ellipsis as DotsIcon, Eye, LayoutHeaderColumns} from '@gravity-ui/icons';
 import {Button, Icon, Label, Menu, Popup} from '@gravity-ui/uikit';
 import type {Node} from 'prosemirror-model';
 import type {EditorView} from 'prosemirror-view';
 
-import {cn} from 'src/classname';
 import {SharedStateKey} from 'src/extensions/behavior/SharedState';
 import {TextAreaFixed as TextArea} from 'src/forms/TextInput';
 import {i18n} from 'src/i18n/common';
+import {i18n as i18nTemplates} from 'src/i18n/yfm-html-block';
 import {debounce} from 'src/lodash';
 import {useAutoSave, useBooleanState, useElementState} from 'src/react-utils/hooks';
 import {useSharedEditingState} from 'src/react-utils/useSharedEditingState';
 import {removeNode} from 'src/utils/remove-node';
 
 import {YfmHtmlBlockConsts} from '../YfmHtmlBlockSpecs/const';
 import type {YfmHtmlBlockOptions} from '../index';
+import {type HtmlTemplate, mergeTemplatesById, readStoredTemplates} from '../templates';
 import type {YfmHtmlBlockEntitySharedState} from '../types';
 
+import {TemplatesPopup} from './TemplatesPopup';
+import {STOP_EVENT_CLASSNAME, cnYfmHtmlBlock} from './const';
+
 import './YfmHtmlBlock.scss';
 
-export const cnYfmHtmlBlock = cn('yfm-html-block');
-export const STOP_EVENT_CLASSNAME = 'prosemirror-stop-event';
+export {STOP_EVENT_CLASSNAME, cnYfmHtmlBlock} from './const';
 
 const b = cnYfmHtmlBlock;
 
@@ -245,7 +248,14 @@ export const YfmHtmlBlockView: React.FC<{
     options: YfmHtmlBlockOptions;
     view: EditorView;
 }> = ({onChange, node, getPos, view, options}) => {
-    const {useConfig, sanitize, styles, baseTarget = '_parent', head: headContent = ''} = options;
+    const {
+        useConfig,
+        sanitize,
+        styles,
+        baseTarget = '_parent',
+        head: headContent = '',
+        templates,
+    } = options;
     const entityId: string = node.attrs[YfmHtmlBlockConsts.NodeAttrs.EntityId];
     const entityKey = useMemo(
         () => SharedStateKey.define<YfmHtmlBlockEntitySharedState>({name: entityId}),
@@ -258,6 +268,22 @@ export const YfmHtmlBlockView: React.FC<{
     const [menuOpen, _openMenu, closeMenu, toggleMenuOpen] = useBooleanState(false);
     const [anchorElement, setAnchorElement] = useElementState();
 
+    const allowAdd = Boolean(templates?.allowAdd);
+    const [storedTemplates, setStoredTemplates] = useState<HtmlTemplate[]>(readStoredTemplates);
+    const effectiveTemplates = useMemo(
+        () => mergeTemplatesById(templates?.items ?? [], storedTemplates),
+        [templates?.items, storedTemplates],
+    );
+    const showTemplatesButton =
+        Boolean(templates?.showButton) && (allowAdd || effectiveTemplates.length > 0);
+    const [templatesOpen, , closeTemplates, toggleTemplatesOpen] = useBooleanState(false);
+    const [templatesAnchor, setTemplatesAnchor] = useElementState();
+
+    const applyTemplate = (template: HtmlTemplate) => {
+        onChange({[YfmHtmlBlockConsts.NodeAttrs.srcdoc]: template.content});
+        closeTemplates();
+    };
+
     if (editing) {
         return (
             <CodeEditMode
@@ -296,6 +322,28 @@ export const YfmHtmlBlockView: React.FC<{
             <YfmHtmlBlockPreview html={resultHtml} onClick={setEditing} config={config} />
 
             <div className={b('menu')}>
+                {showTemplatesButton && (
+                    <>
+                        <Button
+                            onClick={toggleTemplatesOpen}
+                            ref={setTemplatesAnchor}
+                            size="s"
+                            className={STOP_EVENT_CLASSNAME}
+                            aria-label={i18nTemplates('templates')}
+                        >
+                            <Icon data={LayoutHeaderColumns} className={STOP_EVENT_CLASSNAME} />
+                        </Button>
+                        <TemplatesPopup
+                            anchor={templatesAnchor}
+                            open={templatesOpen}
+                            templates={effectiveTemplates}
+                            allowAdd={allowAdd}
+                            onClose={closeTemplates}
+                            onApply={applyTemplate}
+                            onAdded={setStoredTemplates}
+                        />
+                    </>
+                )}
                 <Button
                     onClick={toggleMenuOpen}
                     ref={setAnchorElement}

packages/editor/src/extensions/additional/YfmHtmlBlock/YfmHtmlBlockNodeView/const.ts

@@ -0,0 +1,4 @@
+import {cn} from 'src/classname';
+
+export const cnYfmHtmlBlock = cn('yfm-html-block');
+export const STOP_EVENT_CLASSNAME = 'prosemirror-stop-event';

packages/editor/src/extensions/additional/YfmHtmlBlock/index.ts

@@ -7,6 +7,7 @@ import {WYfmHtmlBlockNodeView} from './YfmHtmlBlockNodeView';
 import {YfmHtmlBlockSpecs} from './YfmHtmlBlockSpecs';
 import {YfmHtmlBlockAction} from './YfmHtmlBlockSpecs/const';
 import {addYfmHtmlBlock} from './actions';
+import type {YfmHtmlBlockTemplatesOptions} from './templates';
 
 export interface YfmHtmlBlockOptions extends Omit<
     PluginOptions,
@@ -17,6 +18,7 @@ export interface YfmHtmlBlockOptions extends Omit<
         enabled: boolean;
         delay?: number; // по умолчанию 1000ms
     };
+    templates?: YfmHtmlBlockTemplatesOptions;
 }
 
 export const YfmHtmlBlock: ExtensionAuto<YfmHtmlBlockOptions> = (

packages/editor/src/extensions/additional/YfmHtmlBlock/templates/index.ts

@@ -0,0 +1,8 @@
+export type {HtmlTemplate, YfmHtmlBlockTemplatesOptions} from './types';
+export {parseTemplates} from './parse';
+export {
+    YFM_HTML_BLOCK_TEMPLATES_STORAGE_KEY,
+    mergeTemplatesById,
+    readStoredTemplates,
+    saveTemplates,
+} from './storage';

packages/editor/src/extensions/additional/YfmHtmlBlock/templates/parse.test.ts

@@ -0,0 +1,49 @@
+import {parseTemplates} from './parse';
+
+describe('parseTemplates', () => {
+    it('parses a single template with id and title', () => {
+        const result = parseTemplates(
+            '<template id="hero" title="Hero block"><div>Hello</div></template>',
+        );
+
+        expect(result).toEqual([{id: 'hero', title: 'Hero block', content: '<div>Hello</div>'}]);
+    });
+
+    it('parses multiple templates at once', () => {
+        const result = parseTemplates(`
+            <template id="a" title="First"><p>1</p></template>
+            <template id="b" title="Second"><p>2</p></template>
+        `);
+
+        expect(result).toHaveLength(2);
+        expect(result[0]).toMatchObject({id: 'a', title: 'First', content: '<p>1</p>'});
+        expect(result[1]).toMatchObject({id: 'b', title: 'Second', content: '<p>2</p>'});
+    });
+
+    it('falls back title to id when title is missing', () => {
+        const [template] = parseTemplates('<template id="only-id"><span>x</span></template>');
+
+        expect(template.id).toBe('only-id');
+        expect(template.title).toBe('only-id');
+    });
+
+    it('generates an id when it is missing', () => {
+        const [template] = parseTemplates('<template title="No id"><span>x</span></template>');
+
+        expect(template.id).toBeTruthy();
+        expect(template.title).toBe('No id');
+    });
+
+    it('treats input without template tags as a single template', () => {
+        const result = parseTemplates('<div class="card">card</div>');
+
+        expect(result).toHaveLength(1);
+        expect(result[0].content).toBe('<div class="card">card</div>');
+        expect(result[0].id).toBeTruthy();
+    });
+
+    it('returns an empty array for blank input', () => {
+        expect(parseTemplates('   ')).toEqual([]);
+        expect(parseTemplates('')).toEqual([]);
+    });
+});