Воркфлоу фильтрации и модификации блоков Gutenberg через React

┌────────────────────────────────────────────────────────────────────────┐
│                   1. РАСШИРЕНИЕ СХЕМЫ БЛОКА                            │
│                 blocks.registerBlockType                               │
│       Инъекция новых атрибутов (attributes) в реестр метаданных        │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
         ┌──────────────────────────┴──────────────────────────┐
         ▼                                                     ▼
┌─────────────────────────────────┐   ┌──────────────────────────────────┐
│      2. РАСШИРЕНИЕ ИНТЕРФЕЙСА   │   │      3. ХОЛСТ РЕДАКТОРА          │
│        editor.BlockEdit (HOC)   │   │     editor.BlockListBlock (HOC)  │
│  - Внедрение в InspectorControls│   │  - Классы обертки на холсте      │
│  - Панели настроек (PanelBody)  │   │  - Бейджи и маркеры для авторов  │
└────────────────┬────────────────┘   └──────────────────────────────────┘
                 │
                 ▼
┌────────────────────────────────────────────────────────────────────────┐
│                   4. КЛИЕНТСКАЯ СЕРИАЛИЗАЦИЯ                           │
│                 blocks.getSaveContent.extraProps                       │
│  Запись атрибутов в HTML-тег при сохранении (data-*, class, style)     │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                   5. СЕРВЕРНАЯ ПОСТ-ОБРАБОТКА (PHP)                    │
│                 render_block / WP_HTML_Tag_Processor                   │
│   Безопасная модификация HTML перед отправкой в браузер клиента        │
└────────────────────────────────────────────────────────────────────────┘

import { addFilter } from '@wordpress/hooks';
import type { BlockSettings } from '@wordpress/blocks';

interface ExtendedAttributes {
  agenticAnimation?: {
    type: 'string';
    default: string;
  };
  agenticLightbox?: {
    type: 'boolean';
    default: boolean;
  };
}

/**
 * Расширяем схему стандартных блоков core/image и core/group новыми атрибутами
 */
function addCustomBlockAttributes(
  settings: BlockSettings<any>,
  name: string
): BlockSettings<any> {
  // Фильтруем только целевые блоки ядра
  if (!['core/image', 'core/group', 'core/cover'].includes(name)) {
    return settings;
  }

  const extendedAttributes: ExtendedAttributes = {
    agenticAnimation: {
      type: 'string',
      default: 'none',
    },
    agenticLightbox: {
      type: 'boolean',
      default: false,
    },
  };

  return {
    ...settings,
    attributes: {
      ...settings.attributes,
      ...extendedAttributes,
    },
  };
}

addFilter(
  'blocks.registerBlockType',
  'agenticlab/extended-attributes',
  addCustomBlockAttributes
);

import React from 'react';
import { createHigherOrderComponent } from '@wordpress/compose';
import { InspectorControls } from '@wordpress/block-editor';
import { PanelBody, SelectControl, ToggleControl } from '@wordpress/components';
import { addFilter } from '@wordpress/hooks';
import { __ } from '@wordpress/i18n';

interface BlockEditProps {
  name: string;
  attributes: {
    agenticAnimation?: string;
    agenticLightbox?: boolean;
    [key: string]: any;
  };
  setAttributes: (attrs: Record<string, any>) => void;
  [key: string]: any;
}

/**
 * HOC-компонент, внедряющий панель «Эффекты и интерактивность» в InspectorControls
 */
const withCustomControls = createHigherOrderComponent(
  (BlockEdit: React.ComponentType<any>) => {
    return (props: BlockEditProps) => {
      // Применяем настройки только к разрешенным блокам
      if (!['core/image', 'core/group', 'core/cover'].includes(props.name)) {
        return <BlockEdit {...props} />;
      }

      const { attributes, setAttributes } = props;
      const { agenticAnimation, agenticLightbox } = attributes;

      const animationOptions = [
        { label: __('Без анимации', 'agenticlab'), value: 'none' },
        { label: __('Плавное появление (Fade Up)', 'agenticlab'), value: 'fade-up' },
        { label: __('Масштабирование (Zoom In)', 'agenticlab'), value: 'zoom-in' },
        { label: __('Сдвиг слева (Slide Right)', 'agenticlab'), value: 'slide-right' },
      ];

      return (
        <>
          {/* Рендерим оригинальный компонент блока ядра */}
          <BlockEdit {...props} />

          {/* Внедряем свою вкладку в боковую панель редактора */}
          <InspectorControls>
            <PanelBody 
              title={__('Спецэффекты Fullstack Agentic Lab', 'agenticlab')} 
              icon="star-filled"
              initialOpen={false}
            >
              <SelectControl
                label={__('Анимация при скролле', 'agenticlab')}
                value={agenticAnimation || 'none'}
                options={animationOptions}
                onChange={(val: string) => setAttributes({ agenticAnimation: val })}
                help={__('Анимация будет воспроизведена при появлении блока во Viewport.', 'agenticlab')}
              />

              {props.name === 'core/image' && (
                <ToggleControl
                  label={__('Всплывающее окно (Lightbox)', 'agenticlab')}
                  checked={Boolean(agenticLightbox)}
                  onChange={(val: boolean) => setAttributes({ agenticLightbox: val })}
                  help={__('Увеличение изображения по клику без перехода на новую страницу.', 'agenticlab')}
                />
              )}
            </PanelBody>
          </InspectorControls>
        </>
      );
    };
  },
  'withCustomControls'
);

addFilter(
  'editor.BlockEdit',
  'agenticlab/with-custom-controls',
  withCustomControls
);

<?php
/**
 * Серверная пост-обработка блоков с добавлением интерактивных атрибутов.
 */

declare(strict_types=1);

namespace AgenticLab\Filters;

use WP_HTML_Tag_Processor;

defined('ABSPATH') || exit;

add_filter('render_block', function (string $block_content, array $block): string {
    // 1. Проверяем, есть ли сохраненные кастомные атрибуты
    $attrs = $block['attrs'] ?? [];
    $animation = $attrs['agenticAnimation'] ?? 'none';
    $lightbox  = $attrs['agenticLightbox'] ?? false;

    if ($animation === 'none' && !$lightbox) {
        return $block_content;
    }

    // 2. Инициализируем быстрый потоковый парсер тегов ядра
    $processor = new WP_HTML_Tag_Processor($block_content);

    // 3. Обработка блока изображения
    if ($block['blockName'] === 'core/image') {
        // Находим тег <figure> для анимации
        if ($processor->next_tag(['tag_name' => 'FIGURE'])) {
            if ($animation !== 'none') {
                $processor->add_class('agentic-animated');
                $processor->set_attribute('data-aos', esc_attr($animation));
            }
        }

        // Если включен Lightbox, находим вложенный тег <img>
        if ($lightbox && $processor->next_tag(['tag_name' => 'IMG'])) {
            $processor->add_class('agentic-lightbox-trigger');
            $processor->set_attribute('data-lightbox-enabled', 'true');
        }

        return $processor->get_updated_html();
    }

    // 4. Обработка контейнеров core/group и core/cover
    if (in_array($block['blockName'], ['core/group', 'core/cover'], true)) {
        if ($processor->next_tag()) {
            if ($animation !== 'none') {
                $processor->add_class('agentic-animated');
                $processor->set_attribute('data-aos', esc_attr($animation));
            }
            return $processor->get_updated_html();
        }
    }

    return $block_content;
}, 10, 2);

import { registerBlockStyle, unregisterBlockStyle } from '@wordpress/blocks';
import domReady from '@wordpress/dom-ready';

domReady(() => {
  // Добавляем фирменный стиль карточки для стандартного блока цитаты
  registerBlockStyle('core/quote', {
    name: 'agentic-callout',
    label: 'Инженерный акцент',
    isDefault: false,
  });

  // Добавляем стиль градиентного бордера для кнопки
  registerBlockStyle('core/button', {
    name: 'agentic-gradient-glow',
    label: 'Свечение',
    isDefault: false,
  });

  // Отключаем ненужный стандартный стиль ядра, если он конфликтует с дизайном
  unregisterBlockStyle('core/separator', 'dots');
});

if (!['core/image'].includes(props.name)) {
  return <BlockEdit {...props} />;
}