@dxtmisha/wiki 0.24.3 → 0.39.1

package/src/media/functional/ru/metaManager.mdx

@@ -0,0 +1,376 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/functional/ru/Classes/MetaManager'/>
+
+# Класс MetaManager
+
+Класс для работы с HTML мета-тегами с автоматической синхронизацией DOM и безопасным кодированием атрибутов. Обеспечивает чтение, обновление и генерацию мета-тегов для SEO-оптимизации и интеграции с социальными сетями (Open Graph, Twitter Cards).
+
+## Основные возможности
+
+- **Синхронизация DOM** — автоматическое обновление мета-тегов в head документа
+- **Поддержка двух форматов** — работа с атрибутами `name` и `property`
+- **Генерация HTML** — преобразование мета-тегов в HTML-строки для серверного рендеринга
+- **Безопасное кодирование** — автоматическое экранирование специальных символов в атрибутах
+- **Типобезопасность** — поддержка TypeScript с дженериками для определения типов
+- **Гибкий API** — цепочечные методы для удобного использования
+- **Совместимость с SSR** — работает в браузере и серверной среде
+- **Автоинициализация** — считывает существующие мета-теги из DOM при создании
+
+## Конструктор
+
+### `constructor`
+
+Создает экземпляр MetaManager с указанными параметрами и автоматически считывает текущие мета-теги из DOM.
+
+**Параметры:**
+- `listMeta: string[]` — список имен мета-тегов для управления
+- `isProperty?: boolean` — использовать атрибут `property` вместо `name` (по умолчанию: `false`)
+
+```javascript
+import { MetaManager } from '@dxtmisha/functional'
+
+// Стандартные мета-теги (атрибут name)
+const meta = new MetaManager([
+  'description',
+  'keywords',
+  'author'
+])
+
+// Мета-теги Open Graph (атрибут property)
+const ogMeta = new MetaManager([
+  'og:title',
+  'og:description',
+  'og:image',
+  'og:url'
+], true)
+
+// Twitter Cards
+const twitterMeta = new MetaManager([
+  'twitter:card',
+  'twitter:title',
+  'twitter:description',
+  'twitter:image'
+])
+```
+
+## Методы запроса данных
+
+### `getListMeta`
+
+Возвращает список имен управляемых мета-тегов.
+
+**Возвращает:** `string[]` — массив имен мета-тегов
+
+```javascript
+const meta = new MetaManager(['description', 'keywords', 'author'])
+
+const names = meta.getListMeta()
+// ['description', 'keywords', 'author']
+
+// Проверка управляемого тега
+const isManaged = names.includes('description') // true
+
+// Итерация по управляемым тегам
+names.forEach(name => {
+  console.log(`Управление: ${name}`)
+})
+```
+
+### `getItem`
+
+Получает содержимое мета-тега по имени из внутреннего хранилища.
+
+**Параметры:**
+- `name: string` — имя мета-тега
+
+**Возвращает:** `string` — содержимое мета-тега (пустая строка если не установлен)
+
+```javascript
+const meta = new MetaManager(['description', 'keywords', 'author'])
+
+// Получить meta description
+const description = meta.get('description')
+
+// Получить keywords
+const keywords = meta.get('keywords')
+
+// Несуществующий тег возвращает пустую строку
+const missing = meta.get('non-existent') // ''
+
+// Использование в условиях
+if (meta.get('description')) {
+  console.log('Description установлен')
+}
+```
+
+### `getItems`
+
+Возвращает все мета-теги в виде объекта.
+
+**Возвращает:** `Record<string, string | undefined>` — объект со всеми мета-тегами
+
+```javascript
+const meta = new MetaManager(['description', 'keywords', 'author'])
+
+const allMeta = meta.getItems()
+// { description: '...', keywords: '...', author: '...' }
+
+// Проверка всех мета-тегов
+Object.keys(allMeta).forEach(key => {
+  console.log(`${key}: ${allMeta[key]}`)
+})
+
+// Использование в валидации
+const hasAllTags = Object.values(allMeta).every(value => value !== '')
+
+// Экспорт для логирования
+console.log('Текущее состояние мета:', allMeta)
+```
+
+## Методы управления данными
+
+### `set`
+
+Устанавливает содержимое мета-тега во внутреннем хранилище и обновляет или создает соответствующий мета-элемент в DOM.
+
+**Параметры:**
+- `name: string` — имя мета-тега
+- `content: string` — содержимое мета-тега
+
+**Возвращает:** `this` — для цепочечных вызовов
+
+```javascript
+const meta = new MetaManager(['description', 'keywords', 'author'])
+
+// Установить один мета-тег
+meta.set('description', 'Описание сайта')
+
+// Цепочка обновлений
+meta
+  .set('description', 'Мой замечательный сайт')
+  .set('keywords', 'веб, разработка, javascript')
+  .set('author', 'Иван Иванов')
+
+// Динамическое обновление
+const updateSEO = (pageData) => {
+  meta
+    .set('description', pageData.description)
+    .set('keywords', pageData.keywords)
+}
+
+// Удаление мета-тега
+meta.set('temporary', '')
+```
+
+### `setByList`
+
+Устанавливает несколько мета-тегов из объекта.
+
+**Параметры:**
+- `metaList: Record<string, string | undefined>` — объект с именами и содержимым мета-тегов
+
+**Возвращает:** `this` — для цепочечных вызовов
+
+```javascript
+const meta = new MetaManager(['description', 'keywords', 'author'])
+
+// Установить несколько тегов сразу
+meta.setByList({
+  description: 'Мой замечательный сайт',
+  keywords: 'веб, разработка, javascript',
+  author: 'Иван Иванов'
+})
+
+// Динамическое обновление страницы
+const updatePageMeta = (page) => {
+  meta.setByList(page.meta)
+}
+
+// Из ответа API
+fetch('/api/page-meta')
+  .then(res => res.json())
+  .then(data => meta.setByList(data))
+
+// Частичные обновления
+meta.setByList({
+  description: 'Обновленное описание'
+  // Остальные теги остаются без изменений
+})
+```
+
+### `html`
+
+Возвращает все мета-теги в виде HTML-строки с безопасным кодированием атрибутов. Полезно для серверного рендеринга.
+
+**Возвращает:** `string` — HTML-строка с мета-тегами
+
+```javascript
+const meta = new MetaManager(['description', 'keywords', 'author'])
+
+meta.setByList({
+  description: 'Мой сайт с "кавычками" & спецсимволами',
+  keywords: 'веб, javascript',
+  author: 'Иван Иванов'
+})
+
+const htmlString = meta.html()
+// <meta name="description" content="Мой сайт с &quot;кавычками&quot; &amp; спецсимволами">
+// <meta name="keywords" content="веб, javascript">
+// <meta name="author" content="Иван Иванов">
+
+// Использование в SSR шаблонах
+const htmlTemplate = `
+<!DOCTYPE html>
+<html>
+<head>
+  ${meta.html()}
+  <title>Заголовок страницы</title>
+</head>
+<body>...</body>
+</html>
+`
+
+// Пример с Express.js
+app.get('/page', (req, res) => {
+  const meta = new MetaManager(['description', 'keywords'])
+  meta.setByList(req.pageData.meta)
+
+  res.send(`
+    <html>
+      <head>${meta.html()}</head>
+      <body>...</body>
+    </html>
+  `)
+})
+```
+
+## Практические примеры
+
+### Управление SEO
+
+```javascript
+const seoMeta = new MetaManager([
+  'description',
+  'keywords',
+  'author',
+  'robots',
+  'viewport'
+])
+
+// Установка SEO тегов
+seoMeta.setByList({
+  description: 'Полное руководство по веб-разработке',
+  keywords: 'веб, html, css, javascript, учебник',
+  author: 'Команда WebDev',
+  robots: 'index, follow',
+  viewport: 'width=device-width, initial-scale=1.0'
+})
+
+// Обновление при смене маршрута
+router.on('change', (route) => {
+  seoMeta.setByList(route.meta)
+})
+```
+
+### Интеграция Open Graph
+
+```javascript
+const ogMeta = new MetaManager([
+  'og:title',
+  'og:description',
+  'og:image',
+  'og:url',
+  'og:type',
+  'og:site_name'
+], true)
+
+// Установка данных Open Graph
+ogMeta.setByList({
+  'og:title': 'Потрясающий заголовок статьи',
+  'og:description': 'Эта статья взорвет ваш мозг',
+  'og:image': 'https://example.com/image.jpg',
+  'og:url': 'https://example.com/article',
+  'og:type': 'article',
+  'og:site_name': 'Мой сайт'
+})
+
+// Для шаринга в соцсетях
+const shareData = {
+  title: ogMeta.get('og:title'),
+  description: ogMeta.get('og:description'),
+  image: ogMeta.get('og:image')
+}
+```
+
+### Мультиплатформенное управление мета-тегами
+
+```javascript
+// Создание менеджеров для разных платформ
+const standardMeta = new MetaManager(['description', 'keywords'])
+const ogMeta = new MetaManager(['og:title', 'og:description', 'og:image'], true)
+const twitterMeta = new MetaManager(['twitter:card', 'twitter:title', 'twitter:description'])
+
+// Обновление всех платформ
+const updateAllMeta = (data) => {
+  standardMeta.setByList({
+    description: data.description,
+    keywords: data.keywords
+  })
+
+  ogMeta.setByList({
+    'og:title': data.title,
+    'og:description': data.description,
+    'og:image': data.image
+  })
+
+  twitterMeta.setByList({
+    'twitter:card': 'summary_large_image',
+    'twitter:title': data.title,
+    'twitter:description': data.description
+  })
+}
+
+// Генерация объединенного HTML для SSR
+const allMetaHTML = [
+  standardMeta.html(),
+  ogMeta.html(),
+  twitterMeta.html()
+].join('')
+```
+
+### Динамическое обновление страниц
+
+```javascript
+const meta = new MetaManager(['description', 'keywords'])
+
+// Single Page Application
+const loadPage = async (pageId) => {
+  const pageData = await fetch(`/api/pages/${pageId}`).then(r => r.json())
+
+  // Обновление мета-тегов
+  meta.setByList(pageData.meta)
+
+  // Обновление заголовка
+  document.title = pageData.title
+}
+
+// Интеграция с React/Vue
+useEffect(() => {
+  meta.set('description', page.description)
+  return () => {
+    // Очистка при необходимости
+    meta.set('description', '')
+  }
+}, [page])
+```
+
+## Примечания
+
+- Конструктор автоматически считывает существующие мета-теги из DOM с помощью метода `update()`
+- Методы, изменяющие DOM, проверяют среду выполнения через `isDomRuntime()` перед доступом к `document`
+- Метод `html()` использует функцию `encodeAttribute()` для предотвращения XSS при внедрении в SSR шаблоны
+- Специальные символы в содержимом автоматически экранируются: `"` → `&quot;`, `&` → `&amp;` и т.д.
+- Когда мета-тег не существует в DOM, `set()` создает его в `document.head`
+- Пустые строки являются допустимыми значениями и обновят содержимое мета-тега на пустое
+- Класс работает как в браузере, так и в Node.js (SSR) окружении