npm package: @opengis/richtext
Description: ## 📋 Опис
Author: Softpro
Latest version: 0.0.45

# VsRichtext - Потужний Rich Text Editor для Vue 3

## 📋 Опис

**VsRichtext** - це сучасний, повнофункціональний rich text редактор для Vue 3, побудований на базі TipTap. Компонент надає широкий спектр можливостей для редагування тексту, включаючи форматування, вставку медіа-контенту, роботу з таблицями та багато іншого.

## ✨ Основні можливості

### 🎨 Форматування тексту
- **Жирний текст** - зручне перемикання жирного шрифту
- **Курсив** - підкреслення важливих частин тексту
- **Підкреслення** - виділення ключових моментів
- **Закреслення** - позначення застарілої інформації
- **Верхній/нижній індекс** - для математичних формул та хімічних позначень

### 🎯 Типографіка
- **Заголовки** - 6 рівнів заголовків (H1-H6) з автоматичним стилюванням
- **Параграфи** - зручне форматування основних блоків тексту
- **Цитати** - виділення важливих цитат зі спеціальним стилюванням
- **Код** - вбудований код та блоки коду з підсвічуванням синтаксису

### 🌈 Кольори та стилі
- **Колір тексту** - вибір з палітри кольорів або власний колір
- **Колір фону** - виділення тексту кольором фону
- **Підсвічування** - маркерне виділення важливих частин
- **Шрифти** - вибір сімейства шрифтів
- **Розмір шрифту** - налаштування розміру тексту

### 📝 Структурування контенту
- **Списки** - марковані та нумеровані списки
- **Вирівнювання** - ліві, центральні, праві та по ширині
- **Горизонтальні лінії** - розділення контенту
- **Таблиці** - повнофункціональні таблиці з можливістю редагування

### 🔗 Медіа та посилання
- **Посилання** - створення та редагування посилань
- **Зображення** - завантаження та вставка зображень
- **Файли** - підтримка завантаження файлів

### 🛠️ Додаткові функції
- **HTML режим** - прямий редагування HTML коду з Monaco Editor
- **Повноекранний режим** - зручне редагування на весь екран
- **Історія змін** - відміна та повернення дій
- **Очищення форматування** - швидке видалення всіх стилів
- **Довідка** - вбудована система допомоги

## 🚀 Встановлення

```bash
npm install @opengis/richtext
```

## 📖 Використання

### Базове використання

```vue
<template>
  <div>
    <VsRichtext v-model="content" />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import VsRichtext from '@opengis/richtext'

const content = ref('')
</script>
```

### Налаштування висоти

```vue
<VsRichtext v-model="content" height="500px" />
```

### Кастомний toolbar

```vue
<VsRichtext 
  v-model="content" 
  :toolbar="['bold', 'italic', 'underline', 'link']" 
/>
```

### Використання готових наборів

```vue
<!-- Базовий набір -->
<VsRichtext v-model="content" toolbar="basic" />

<!-- Стандартний набір (за замовчуванням) -->
<VsRichtext v-model="content" toolbar="default" />

<!-- Повний набір -->
<VsRichtext v-model="content" toolbar="full" />
```

## 🎛️ API

### Props

| Параметр | Тип | За замовчуванням | Опис |
|----------|-----|------------------|------|
| `modelValue` | `String` | `""` | Вміст редактора (v-model) |
| `height` | `String` | `"300px"` | Висота редактора |
| `toolbar` | `Array \| String` | `"default"` | Набір кнопок toolbar |

### Toolbar Presets

#### `basic` - Базовий набір
- Історія змін
- Жирний, курсив, підкреслення, закреслення
- Вирівнювання тексту
- Списки (марковані та нумеровані)
- Посилання та зображення
- Очищення форматування
- Довідка

#### `default` - Стандартний набір (рекомендований)
- Всі функції з `basic`
- Заголовки
- Кольори тексту та фону
- Підсвічування
- Блоки коду
- Таблиці
- Горизонтальні лінії
- Повноекранний режим
- HTML режим

#### `full` - Повний набір
- Всі функції з `default`
- Сімейство шрифтів
- Розмір шрифту
- Цитати
- Верхній/нижній індекс
- Історія змін

### Доступні контроли

| Контроль | Опис | Preset |
|----------|------|--------|
| `history` | Історія змін (відміна/повернення) | full |
| `heading` | Заголовки (H1-H6) | default, full |
| `font_family` | Сімейство шрифтів | full |
| `font_size` | Розмір шрифту | full |
| `bold` | Жирний текст | basic, default, full |
| `italic` | Курсив | basic, default, full |
| `underline` | Підкреслення | basic, default, full |
| `strike` | Закреслення | basic, default, full |
| `color` | Колір тексту | default, full |
| `background_color` | Колір фону | default, full |
| `highlight` | Підсвічування | default, full |
| `text_align` | Вирівнювання тексту | basic, default, full |
| `bullet_list` | Марковані списки | basic, default, full |
| `ordered_list` | Нумеровані списки | basic, default, full |
| `blockquote` | Цитати | full |
| `codeblock` | Блоки коду | default, full |
| `table` | Таблиці | default, full |
| `link` | Посилання | basic, default, full |
| `image` | Зображення | basic, default, full |
| `horizontal_rule` | Горизонтальні лінії | default, full |
| `superscript` | Верхній індекс | full |
| `subscript` | Нижній індекс | full |
| `clear_formatting` | Очищення форматування | basic, default, full |
| `fullscreen` | Повноекранний режим | default, full |
| `html_mode` | HTML режим | default, full |
| `help` | Довідка | basic, default, full |

## 🌍 Міжнародна підтримка (i18n)

Компонент підтримує багатомовність з наступними мовами:
- **Українська** (за замовчуванням)
- **Англійська**

### Налаштування мови

```javascript
import { createI18n } from 'vue-i18n'
import i18n from '@opengis/richtext/i18n'

const app = createApp(App)
app.use(i18n)
```

## 🎨 Стилізація

Компонент використовує Tailwind CSS для стилізації. Всі стилі можна кастомізувати через CSS змінні або прямим перевизначенням класів.

### Кастомні стилі

```css
/* Кастомізація toolbar */
.vs-richtext .toolbar {
  background-color: #f8f9fa;
  border-bottom: 1px solid #e9ecef;
}

/* Кастомізація редактора */
.vs-richtext .editor-content {
  min-height: 200px;
  padding: 16px;
}
```

## 🔧 Розширення функціоналу

### Додавання власних контролів

```vue
<!-- Власний контроль -->
<template>
  <button @click="customAction" class="custom-control">
    Custom Action
  </button>
</template>

<script setup>
const props = defineProps({ editor: Object })

const customAction = () => {
  if (props.editor) {
    // Ваша логіка
    props.editor.commands.insertContent('Custom content')
  }
}
</script>
```

### Кастомні розширення TipTap

```javascript
import { useRichTextEditor } from '@opengis/richtext/composables'

const { editor } = useRichTextEditor({
  extensions: [
    // Ваші кастомні розширення
    CustomExtension.configure({
      // налаштування
    })
  ]
})
```

## 📱 Адаптивність

Компонент повністю адаптивний та працює на всіх пристроях:
- **Desktop** - повний функціонал з усіма контролами
- **Tablet** - оптимізований інтерфейс
- **Mobile** - спрощений toolbar з основними функціями

## 🎯 HTML режим

HTML режим надає можливість прямого редагування HTML коду з використанням Monaco Editor:

### Особливості HTML режиму:
- **Підсвічування синтаксису** - яскраве підсвічування HTML тегів, атрибутів та значень
- **Автодоповнення** - розумні підказки для HTML атрибутів
- **Форматування коду** - автоматичне форматування HTML
- **Валідація** - перевірка синтаксису HTML
- **Теми** - підтримка світлої та темної теми

## 🗂️ Робота з таблицями

Компонент надає повнофункціональну роботу з таблицями:

### Можливості таблиць:
- **Створення таблиць** - таблиці різних розмірів
- **Додавання рядків/стовпців** - динамічне розширення
- **Видалення рядків/стовпців** - очищення структури
- **Об'єднання клітинок** - створення складних структур
- **Розділення клітинок** - повернення до стандартної структури
- **Зміна розміру** - інтерактивне змінення розмірів
- **Стилювання** - налаштування зовнішнього вигляду

## 📁 Структура проекту

```
src/
├── components/
│   ├── vs-richtext.vue          # Основний компонент
│   ├── controls/                 # Контроли toolbar
│   │   ├── index.ts
│   │   ├── vs-editor-boldtext.vue
│   │   ├── vs-editor-italic.vue
│   │   ├── vs-editor-table.vue
│   │   └── ...
│   ├── helpers/                  # Допоміжні компоненти
│   │   ├── monaco-editor.vue
│   │   ├── handlePaste.js
│   │   ├── customHeading.js
│   │   └── customParagraph.js
│   ├── shared-components/        # Спільні компоненти
│   │   ├── vs-popover.vue
│   │   ├── vs-dialog.vue
│   │   └── vs-form-color-picker.vue
│   └── toolbarPresets.js         # Набори кнопок
├── composables/                  # Vue 3 композабли
│   ├── useRichTextEditor.js
│   ├── useHtmlMode.js
│   └── useFullscreen.js
├── i18n/                        # Міжнародна підтримка
│   ├── i18n.js
│   └── locales/
│       ├── en/
│       └── uk/
└── utils/                       # Утиліти
    ├── index.js
    └── dynamic.position.js
```

## 🔄 Життєвий цикл

### Ініціалізація
1. Створення TipTap редактора з розширеннями
2. Налаштування toolbar з обраними контролами
3. Ініціалізація композаблів (HTML режим, повноекранний режим)
4. Підключення обробників подій

### Оновлення контенту
1. Відстеження змін в редакторі
2. Синхронізація з v-model
3. Оновлення HTML контенту
4. Емітування подій до батьківського компонента

### Очищення
1. Відключення обробників подій
2. Очищення TipTap редактора
3. Знищення Monaco Editor (якщо використовується)

## 🐛 Відомі обмеження

1. **Завантаження файлів** - потребує налаштування backend endpoint
2. **Зображення** - автоматичне зменшення розміру не підтримується
3. **Печатка** - стилі можуть відрізнятися від екрану
4. **Стара браузерна підтримка** - потребує поліфілів для IE11

## 🤝 Внесок у розробку

1. Fork репозиторію
2. Створіть feature branch (`git checkout -b feature/amazing-feature`)
3. Commit зміни (`git commit -m 'Add amazing feature'`)
4. Push до branch (`git push origin feature/amazing-feature`)
5. Створіть Pull Request

## 📄 Ліцензія

Цей проект ліцензовано під MIT License - дивіться файл [LICENSE](LICENSE) для деталей.

## 👥 Автори

- **Softpro** - *Початкова розробка* - [@softpro](https://github.com/softpro)

## 🙏 Подяки

- [TipTap](https://tiptap.dev/) - за чудовий rich text editor
- [Monaco Editor](https://microsoft.github.io/monaco-editor/) - за потужний code editor
- [Vue 3](https://vuejs.org/) - за сучасний фреймворк
- [Tailwind CSS](https://tailwindcss.com/) - за утилітарні CSS класи

---

**VsRichtext** - ваш надійний помічник для створення багатого текстового контенту! 🚀