npm - @dxtmisha/wiki - Versions diffs - 0.39.1 → 0.39.3 - Mend

@dxtmisha/wiki 0.39.1 → 0.39.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2032) hide show

package/src/media/functional/ru/metaTwitter.mdx DELETED Viewed

@@ -1,853 +0,0 @@
-import {Meta} from '@storybook/addon-docs/blocks'
-<Meta title='@dxtmisha/functional/ru/Classes/MetaTwitter'/>
-# Класс MetaTwitter
-Класс для работы с Twitter Card мета-тегами, обеспечивающий красивое отображение контента при публикации ссылок в Twitter (X). Наследует функциональность `MetaManager` и предоставляет типобезопасные методы для управления стандартными Twitter Card тегами.
-## Основные возможности
-- **Типобезопасность** — строгая типизация для всех Twitter Card тегов и типов карточек
-- **Автоматическая синхронизация** — обновление мета-тегов в `<head>` документа
-- **Поддержка всех типов карточек** — summary, summary_large_image, app, player
-- **Удобный API** — специализированные методы для каждого тега
-- **SSR совместимость** — генерация HTML для серверного рендеринга
-- **Валидация типов** — поддержка всех официальных типов Twitter Cards
-- **Цепочечные методы** — возможность последовательной установки значений
-## Конструктор
-### `constructor`
-Создает экземпляр MetaTwitter с предустановленным списком всех поддерживаемых Twitter Card тегов. Автоматически считывает существующие теги из DOM.
-```javascript
-import { MetaTwitter } from '@dxtmisha/functional'
-// Создание экземпляра
-const twitter = new MetaTwitter()
-// Класс автоматически управляет всеми стандартными Twitter Card тегами:
-// twitter:card, twitter:site, twitter:creator, twitter:title,
-// twitter:description, twitter:image и другими
-```
-## Методы получения данных
-### `getCard`
-Получает тип Twitter Card.
-**Возвращает:** `MetaTwitterCard` — тип карточки
-```javascript
-const twitter = new MetaTwitter()
-const cardType = twitter.getCard()
-// 'summary_large_image'
-// Проверка типа карточки
-if (twitter.getCard() === 'summary_large_image') {
-  console.log('Карточка с большим изображением')
-}
-// Условная логика
-switch (twitter.getCard()) {
-  case 'summary':
-    console.log('Обычная карточка')
-    break
-  case 'summary_large_image':
-    console.log('Карточка с большим изображением')
-    break
-  case 'player':
-    console.log('Видео плеер')
-    break
-}
-```
-### `getSite`
-Получает Twitter аккаунт сайта или бренда.
-**Возвращает:** `string` — @username сайта
-```javascript
-const twitter = new MetaTwitter()
-const site = twitter.getSite()
-// '@mywebsite'
-// Использование для атрибуции
-console.log('Сайт принадлежит:', twitter.getSite())
-// Проверка наличия
-if (twitter.getSite()) {
-  console.log('Twitter аккаунт сайта установлен')
-}
-// Извлечение имени без @
-const username = twitter.getSite().replace('@', '')
-```
-### `getCreator`
-Получает Twitter аккаунт автора контента.
-**Возвращает:** `string` — @username автора
-```javascript
-const twitter = new MetaTwitter()
-const creator = twitter.getCreator()
-// '@john_doe'
-// Отображение автора
-console.log('Автор:', twitter.getCreator())
-// Использование в UI
-const authorLink = `https://twitter.com/${twitter.getCreator().replace('@', '')}`
-// Проверка авторства
-if (twitter.getCreator()) {
-  console.log('У контента есть автор')
-}
-```
-### `getUrl`
-Получает URL страницы для Twitter Card.
-**Возвращает:** `string` — URL страницы
-```javascript
-const twitter = new MetaTwitter()
-const url = twitter.getUrl()
-// 'https://example.com/article/my-post'
-// Получение домена
-const domain = new URL(twitter.getUrl()).hostname
-// Проверка совпадения с текущим URL
-if (twitter.getUrl() !== window.location.href) {
-  console.warn('Twitter URL не совпадает с текущим')
-}
-// Создание ссылки для шаринга
-const shareUrl = `https://twitter.com/intent/tweet?url=${encodeURIComponent(twitter.getUrl())}`
-```
-### `getTitle`
-Получает заголовок карточки.
-**Возвращает:** `string` — заголовок карточки
-```javascript
-const twitter = new MetaTwitter()
-const title = twitter.getTitle()
-// 'Удивительная статья о веб-разработке'
-// Использование для отладки
-console.log('Twitter Title:', twitter.getTitle())
-// Проверка длины (рекомендуется до 70 символов)
-if (twitter.getTitle().length > 70) {
-  console.warn('Заголовок слишком длинный для Twitter')
-}
-// Использование в превью
-const previewTitle = twitter.getTitle()
-```
-### `getDescription`
-Получает описание карточки.
-**Возвращает:** `string` — описание карточки
-```javascript
-const twitter = new MetaTwitter()
-const description = twitter.getDescription()
-// 'Подробное руководство по созданию...'
-// Проверка длины (рекомендуется до 200 символов)
-if (twitter.getDescription().length > 200) {
-  console.warn('Описание слишком длинное')
-}
-// Обрезка для превью
-const shortDesc = twitter.getDescription().substring(0, 150) + '...'
-// Использование в мета-данных
-console.log('Twitter Description:', twitter.getDescription())
-```
-### `getImage`
-Получает URL изображения карточки.
-**Возвращает:** `string` — URL изображения
-```javascript
-const twitter = new MetaTwitter()
-const imageUrl = twitter.getImage()
-// 'https://example.com/images/twitter-card.jpg'
-// Предзагрузка изображения
-const img = new Image()
-img.src = twitter.getImage()
-// Проверка наличия
-if (!twitter.getImage()) {
-  console.warn('Twitter изображение не установлено')
-}
-// Использование для превью
-const previewImage = twitter.getImage()
-```
-## Методы установки данных
-### `setCard`
-Устанавливает тип Twitter Card.
-**Параметры:**
-- `card: MetaTwitterCard` — тип карточки
-**Возвращает:** `this` — для цепочечных вызовов
-**Доступные типы:**
-- `summary` — карточка-сводка с небольшим изображением
-- `summary_large_image` — карточка с большим изображением (самый популярный)
-- `app` — карточка приложения (для iOS/Android)
-- `player` — карточка с видео/аудио плеером
-```javascript
-import { MetaTwitter, MetaTwitterCard } from '@dxtmisha/functional'
-const twitter = new MetaTwitter()
-// Установка стандартной карточки
-twitter.setCard(MetaTwitterCard.summary)
-// Карточка с большим изображением (рекомендуется)
-twitter.setCard(MetaTwitterCard.summaryLargeImage)
-// Для приложений
-twitter.setCard(MetaTwitterCard.app)
-// Для видео контента
-twitter.setCard(MetaTwitterCard.player)
-// Условная установка
-const cardType = hasLargeImage
-  ? MetaTwitterCard.summaryLargeImage
-  : MetaTwitterCard.summary
-twitter.setCard(cardType)
-```
-### `setSite`
-Устанавливает Twitter аккаунт сайта или бренда.
-**Параметры:**
-- `site: string` — @username сайта
-**Возвращает:** `this` — для цепочечных вызовов
-```javascript
-const twitter = new MetaTwitter()
-// Установка аккаунта сайта
-twitter.setSite('@mywebsite')
-// Можно без @
-twitter.setSite('mywebsite')
-// Из конфигурации
-twitter.setSite(config.twitterHandle)
-// Цепочка методов
-twitter
-  .setSite('@mywebsite')
-  .setCreator('@author')
-// Рекомендации:
-// - Используйте официальный аккаунт бренда
-// - Формат: @username (с @ или без)
-// - Twitter будет показывать "via @username" в карточке
-```
-### `setCreator`
-Устанавливает Twitter аккаунт автора контента.
-**Параметры:**
-- `creator: string` — @username автора
-**Возвращает:** `this` — для цепочечных вызовов
-```javascript
-const twitter = new MetaTwitter()
-// Установка автора
-twitter.setCreator('@john_doe')
-// Из данных пользователя
-twitter.setCreator(article.author.twitterHandle)
-// Динамическое обновление
-const updateAuthor = (author) => {
-  if (author.twitter) {
-    twitter.setCreator(author.twitter)
-  }
-}
-// Цепочка
-twitter
-  .setCreator('@author_name')
-  .setTitle('Заголовок статьи')
-// Рекомендации:
-// - Используйте для атрибуции автора
-// - Twitter покажет "by @username"
-// - Отличается от site (site - для сайта, creator - для автора)
-```
-### `setUrl`
-Устанавливает URL страницы для Twitter Card.
-**Параметры:**
-- `url: string` — URL страницы
-**Возвращает:** `this` — для цепочечных вызовов
-```javascript
-const twitter = new MetaTwitter()
-// Установка URL
-twitter.setUrl('https://example.com/article/my-post')
-// Использование текущего URL
-twitter.setUrl(window.location.href)
-// Очистка query параметров
-const cleanUrl = window.location.origin + window.location.pathname
-twitter.setUrl(cleanUrl)
-// Для SPA
-router.afterEach((to) => {
-  twitter.setUrl(`https://example.com${to.fullPath}`)
-})
-// Абсолютный URL из относительного
-const absoluteUrl = new URL('/article', window.location.origin).href
-twitter.setUrl(absoluteUrl)
-// Рекомендации:
-// - Всегда используйте абсолютные URL
-// - URL должен быть доступен для Twitter бота
-// - Избегайте редиректов
-```
-### `setTitle`
-Устанавливает заголовок карточки.
-**Параметры:**
-- `title: string` — заголовок карточки
-**Возвращает:** `this` — для цепочечных вызовов
-```javascript
-const twitter = new MetaTwitter()
-// Установка заголовка
-twitter.setTitle('Потрясающая статья о веб-разработке')
-// Цепочка методов
-twitter
-  .setTitle('Новый заголовок')
-  .setDescription('Новое описание')
-// Динамическое обновление
-const updateTitle = (newTitle) => {
-  twitter.setTitle(newTitle)
-}
-// Автоматическая генерация
-twitter.setTitle(`${article.title} - ${siteName}`)
-// Обрезка длинного заголовка
-const maxLength = 70
-const shortTitle = article.title.length > maxLength
-  ? article.title.substring(0, maxLength - 3) + '...'
-  : article.title
-twitter.setTitle(shortTitle)
-// Рекомендации:
-// - Максимум 70 символов
-// - Будет отображаться жирным шрифтом
-// - Избегайте дублирования с описанием
-```
-### `setDescription`
-Устанавливает описание карточки.
-**Параметры:**
-- `description: string` — описание карточки
-**Возвращает:** `this` — для цепочечных вызовов
-```javascript
-const twitter = new MetaTwitter()
-// Установка описания
-twitter.setDescription('Полное руководство по созданию веб-приложений с использованием современных технологий')
-// Обрезка длинного текста
-const shortDesc = article.content.substring(0, 200)
-twitter.setDescription(shortDesc)
-// Удаление HTML тегов
-const plainText = article.html.replace(/<[^>]*>/g, '')
-twitter.setDescription(plainText.substring(0, 200))
-// Из excerpt
-twitter.setDescription(article.excerpt || article.content.substring(0, 200))
-// Цепочка
-twitter
-  .setDescription('Описание статьи')
-  .setImage('https://example.com/image.jpg')
-// Рекомендации:
-// - Максимум 200 символов
-// - Twitter может обрезать текст
-// - Добавляйте call-to-action
-// - Избегайте специальных символов
-```
-### `setImage`
-Устанавливает URL изображения карточки.
-**Параметры:**
-- `image: string` — URL изображения
-**Возвращает:** `this` — для цепочечных вызовов
-```javascript
-const twitter = new MetaTwitter()
-// Установка изображения
-twitter.setImage('https://example.com/images/twitter-card.jpg')
-// Абсолютный URL
-const imageUrl = new URL('/images/twitter-image.jpg', window.location.origin).href
-twitter.setImage(imageUrl)
-// Из данных контента
-twitter.setImage(article.featuredImage)
-// Fallback изображение
-twitter.setImage(article.image || '/images/default-twitter.jpg')
-// Для summary карточки (квадратное изображение)
-twitter
-  .setCard(MetaTwitterCard.summary)
-  .setImage('https://example.com/square-image.jpg') // 1:1 ratio
-// Для summary_large_image (широкое изображение)
-twitter
-  .setCard(MetaTwitterCard.summaryLargeImage)
-  .setImage('https://example.com/wide-image.jpg') // 2:1 ratio
-// Рекомендуемые размеры:
-// summary: 120x120 - 1:1 (минимум)
-//          280x150 - оптимально
-// summary_large_image: 300x157 - минимум
-//                      1200x628 - оптимально (как OG)
-//                      Ratio 2:1 или 1.91:1
-// Форматы: JPG, PNG, WebP, GIF
-// Максимальный размер: 5 MB
-```
-## Практические примеры
-### Полная настройка страницы статьи
-```javascript
-import { MetaTwitter, MetaTwitterCard } from '@dxtmisha/functional'
-const twitter = new MetaTwitter()
-// Установка всех основных тегов
-twitter
-  .setCard(MetaTwitterCard.summaryLargeImage)
-  .setTitle('Полное руководство по Twitter Cards')
-  .setDescription('Узнайте, как правильно настроить Twitter Card теги для вашего сайта и улучшить отображение в Twitter')
-  .setUrl('https://example.com/articles/twitter-cards-guide')
-  .setImage('https://example.com/images/twitter-guide.jpg')
-  .setSite('@mywebsite')
-  .setCreator('@author_name')
-// Теперь при публикации в Twitter:
-// - Отобразится красивая карточка с большим изображением
-// - Будет показан заголовок и описание
-// - Появится атрибуция "via @mywebsite by @author_name"
-```
-### Динамическое обновление для SPA
-```javascript
-// Vue Router
-router.afterEach((to) => {
-  const twitter = new MetaTwitter()
-  twitter
-    .setCard(MetaTwitterCard.summaryLargeImage)
-    .setTitle(to.meta.twitterTitle || to.meta.title)
-    .setDescription(to.meta.twitterDescription || to.meta.description)
-    .setUrl(`https://example.com${to.path}`)
-    .setImage(to.meta.twitterImage || '/images/default-twitter.jpg')
-    .setSite('@mywebsite')
-})
-// React Router
-useEffect(() => {
-  const twitter = new MetaTwitter()
-  twitter
-    .setCard(MetaTwitterCard.summaryLargeImage)
-    .setTitle(page.title)
-    .setDescription(page.description)
-    .setUrl(window.location.href)
-    .setImage(page.image)
-    .setSite(config.twitterSite)
-    .setCreator(page.author?.twitter)
-  return () => {
-    // Cleanup если необходимо
-  }
-}, [page])
-```
-### Настройка для разных типов контента
-```javascript
-import { MetaTwitter, MetaTwitterCard } from '@dxtmisha/functional'
-const twitter = new MetaTwitter()
-// Для блог-поста
-const setupBlogPost = (post) => {
-  twitter
-    .setCard(MetaTwitterCard.summaryLargeImage)
-    .setTitle(post.title)
-    .setDescription(post.excerpt)
-    .setUrl(`https://example.com/blog/${post.slug}`)
-    .setImage(post.coverImage)
-    .setSite('@myblog')
-    .setCreator(post.author.twitter)
-}
-// Для новости (с небольшим изображением)
-const setupNews = (news) => {
-  twitter
-    .setCard(MetaTwitterCard.summary)
-    .setTitle(news.headline)
-    .setDescription(news.summary)
-    .setUrl(`https://example.com/news/${news.id}`)
-    .setImage(news.thumbnail)
-    .setSite('@mynews')
-}
-// Для видео
-const setupVideo = (video) => {
-  twitter
-    .setCard(MetaTwitterCard.player)
-    .setTitle(video.title)
-    .setDescription(video.description)
-    .setUrl(`https://example.com/videos/${video.id}`)
-    .setImage(video.thumbnail)
-    .setSite('@myvideos')
-}
-// Для главной страницы
-const setupHomePage = () => {
-  twitter
-    .setCard(MetaTwitterCard.summaryLargeImage)
-    .setTitle('Добро пожаловать на наш сайт')
-    .setDescription('Лучший контент о веб-разработке и технологиях')
-    .setUrl('https://example.com')
-    .setImage('https://example.com/images/home-twitter.jpg')
-    .setSite('@mywebsite')
-}
-```
-### Генерация HTML для SSR
-```javascript
-import { MetaTwitter, MetaTwitterCard } from '@dxtmisha/functional'
-// Express.js сервер
-app.get('/article/:id', async (req, res) => {
-  const article = await getArticle(req.params.id)
-  const twitter = new MetaTwitter()
-  twitter
-    .setCard(MetaTwitterCard.summaryLargeImage)
-    .setTitle(article.title)
-    .setDescription(article.excerpt)
-    .setUrl(`https://example.com/article/${article.id}`)
-    .setImage(article.coverImage)
-    .setSite('@mywebsite')
-    .setCreator(article.author.twitter)
-  const html = `
-    <!DOCTYPE html>
-    <html>
-      <head>
-        <title>${article.title}</title>
-        ${twitter.html()}
-      </head>
-      <body>
-        ${article.content}
-      </body>
-    </html>
-  `
-  res.send(html)
-})
-// Результат в HTML:
-// <meta property="twitter:card" content="summary_large_image">
-// <meta property="twitter:title" content="Заголовок статьи">
-// <meta property="twitter:description" content="Описание...">
-// <meta property="twitter:url" content="https://example.com/article/123">
-// <meta property="twitter:image" content="https://example.com/images/cover.jpg">
-// <meta property="twitter:site" content="@mywebsite">
-// <meta property="twitter:creator" content="@author">
-```
-### Комбинирование с Open Graph
-```javascript
-import { MetaTwitter, MetaOg, MetaTwitterCard, MetaOpenGraphType } from '@dxtmisha/functional'
-const twitter = new MetaTwitter()
-const og = new MetaOg()
-// Общая функция обновления
-const updateSocialMeta = (data) => {
-  // Twitter Cards
-  twitter
-    .setCard(MetaTwitterCard.summaryLargeImage)
-    .setTitle(data.title)
-    .setDescription(data.description)
-    .setUrl(data.url)
-    .setImage(data.image)
-    .setSite(data.twitterSite)
-    .setCreator(data.twitterCreator)
-  // Open Graph
-  og
-    .setType(MetaOpenGraphType.article)
-    .setTitle(data.title)
-    .setDescription(data.description)
-    .setUrl(data.url)
-    .setImage(data.image)
-    .setSiteName(data.siteName)
-    .setLocale('ru_RU')
-}
-// Использование
-updateSocialMeta({
-  title: 'Заголовок статьи',
-  description: 'Описание статьи',
-  url: 'https://example.com/article/123',
-  image: 'https://example.com/images/cover.jpg',
-  twitterSite: '@mywebsite',
-  twitterCreator: '@author',
-  siteName: 'Мой Сайт'
-})
-// Для SSR - объединенный HTML
-const allSocialMetaHTML = twitter.html() + og.html()
-```
-### Интеграция с CMS
-```javascript
-import { MetaTwitter, MetaTwitterCard } from '@dxtmisha/functional'
-// Функция обновления Twitter Card из CMS данных
-const updateTwitterFromCMS = (pageData) => {
-  const twitter = new MetaTwitter()
-  // Определение типа карточки
-  const cardMap = {
-    'post': MetaTwitterCard.summaryLargeImage,
-    'news': MetaTwitterCard.summary,
-    'video': MetaTwitterCard.player
-  }
-  twitter
-    .setCard(cardMap[pageData.contentType] || MetaTwitterCard.summaryLargeImage)
-    .setTitle(pageData.seo?.twitterTitle || pageData.title)
-    .setDescription(pageData.seo?.twitterDescription || pageData.excerpt)
-    .setUrl(pageData.canonicalUrl)
-    .setImage(pageData.seo?.twitterImage || pageData.featuredImage)
-    .setSite(pageData.site.twitterHandle)
-  // Добавление автора если есть
-  if (pageData.author?.twitter) {
-    twitter.setCreator(pageData.author.twitter)
-  }
-  return twitter
-}
-// Использование
-const page = await cms.getPage(pageId)
-updateTwitterFromCMS(page)
-```
-### Валидация и отладка
-```javascript
-import { MetaTwitter } from '@dxtmisha/functional'
-const twitter = new MetaTwitter()
-// Проверка обязательных полей
-const validateTwitterCard = () => {
-  const errors = []
-  if (!twitter.getCard()) errors.push('Отсутствует twitter:card')
-  if (!twitter.getTitle()) errors.push('Отсутствует twitter:title')
-  if (!twitter.getDescription()) errors.push('Отсутствует twitter:description')
-  if (!twitter.getImage()) errors.push('Отсутствует twitter:image')
-  // Проверка длины
-  if (twitter.getTitle().length > 70) {
-    errors.push('twitter:title слишком длинный (>70 символов)')
-  }
-  if (twitter.getDescription().length > 200) {
-    errors.push('twitter:description слишком длинное (>200 символов)')
-  }
-  if (errors.length > 0) {
-    console.error('Twitter Card ошибки:', errors)
-  }
-  return errors.length === 0
-}
-// Вывод всех Twitter Card тегов для отладки
-const debugTwitterCard = () => {
-  console.group('Twitter Card Tags')
-  console.log('Card Type:', twitter.getCard())
-  console.log('Title:', twitter.getTitle())
-  console.log('Description:', twitter.getDescription())
-  console.log('Image:', twitter.getImage())
-  console.log('URL:', twitter.getUrl())
-  console.log('Site:', twitter.getSite())
-  console.log('Creator:', twitter.getCreator())
-  console.groupEnd()
-}
-// Экспорт для тестирования
-const exportTwitterData = () => {
-  return twitter.getItems()
-}
-// Проверка перед публикацией
-const checkBeforePublish = () => {
-  const isValid = validateTwitterCard()
-  if (isValid) {
-    console.log('✓ Twitter Card настроен правильно')
-  } else {
-    console.warn('⚠ Twitter Card требует внимания')
-    debugTwitterCard()
-  }
-  return isValid
-}
-```
-## Рекомендации по использованию
-### Обязательные теги
-Для корректного отображения Twitter Card необходимо установить минимум:
-- `twitter:card` — тип карточки
-- `twitter:title` — заголовок
-- `twitter:description` — описание
-- `twitter:image` — изображение
-### Размеры изображений
-**summary карточка:**
-- **Рекомендуемый размер:** 120×120 px (минимум)
-- **Оптимальный размер:** 280×150 px
-- **Соотношение сторон:** 1:1 (квадратное)
-**summary_large_image карточка:**
-- **Минимальный размер:** 300×157 px
-- **Оптимальный размер:** 1200×628 px (как Open Graph)
-- **Соотношение сторон:** 2:1 или 1.91:1
-- **Максимальный размер файла:** 5 MB
-- **Форматы:** JPG, PNG, WebP, GIF
-### Длина текста
-- **twitter:title:** до 70 символов
-- **twitter:description:** до 200 символов
-- **twitter:site:** @username формат
-- **twitter:creator:** @username формат
-### Атрибуты @username
-- **twitter:site** — официальный Twitter аккаунт сайта/бренда
-  - Показывается как "via @username"
-  - Используется для атрибуции сайта
-- **twitter:creator** — Twitter аккаунт автора контента
-  - Показывается как "by @username"
-  - Используется для атрибуции автора
-### Тестирование
-Проверяйте Twitter Card теги с помощью:
-- [Twitter Card Validator](https://cards-dev.twitter.com/validator) (старая версия)
-- Тестируйте, публикуя тестовую ссылку в Twitter
-- Используйте режим предпросмотра при создании твита
-### Различия с Open Graph
-Twitter Cards может использовать Open Graph теги как fallback:
-- Если `twitter:title` отсутствует, используется `og:title`
-- Если `twitter:description` отсутствует, используется `og:description`
-- Если `twitter:image` отсутствует, используется `og:image`
-Однако рекомендуется устанавливать Twitter Card теги явно для лучшего контроля.
-## Примечания
-- Класс наследует все методы от `MetaManager`, включая `html()`, `getItems()`, `setByList()`
-- Автоматически использует атрибут `property` (как и Open Graph)
-- Все изменения немедленно отражаются в DOM дереве
-- При создании экземпляра автоматически считываются существующие Twitter Card теги из страницы
-- Для SSR используйте метод `html()` для генерации мета-тегов в серверном шаблоне
-- Содержимое автоматически экранируется для предотвращения XSS
-- Twitter может кэшировать карточки, используйте Card Validator для сброса кэша
-- Поддерживаются все официальные типы Twitter Cards