@opengis/richtext 0.0.13 → 0.0.16

package/README.md

@@ -1,170 +1,364 @@
-# @opengis/richtext
-
-<!-- [![NPM version](https://img.shields.io/npm/v/@opengis/richtext?style=plain)](https://www.npmjs.com/package/@opengis/richtext) -->
-
-A powerful and extensible rich text editor component for Vue 3.
-Built with TipTap editor, featuring comprehensive formatting tools, table support, and markdown integration.
-
-## Features
-
-- **Rich Text Formatting**: Bold, italic, underline, strikethrough, superscript, subscript
-- **History Management**: Combined undo/redo functionality with keyboard shortcuts
-- **Help System**: Markdown shortcuts reference popover
-- **Text Alignment**: Left, center, right, justify alignment options
-- **Lists**: Bullet lists and ordered lists with full nesting support
-- **Tables**: Full table support with resizable columns and sticky headers
-- **Links**: Automatic link detection and manual link insertion
-- **Code Support**: Inline code and code blocks with syntax highlighting
-- **Color Support**: Text color and background color picker
-- **Blockquotes**: Styled blockquotes with custom formatting
-- **Images**: Image insertion and management
-- **Markdown Integration**: Built-in markdown to HTML conversion and vice versa
-- **Customizable Toolbar**: Configurable toolbar with selective feature inclusion
-- **Internationalization**: Built-in i18n support (English/Ukrainian)
-- **Responsive Design**: Mobile-friendly and fully responsive
-- **TypeScript Support**: Written in TypeScript with full type definitions
-- **Vue 3 Composition API**: Modern Vue 3 with `<script setup>` syntax
-
-## Documentation
-
-### Local Development
-To run the documentation locally:
-
-```bash
-cd docs
-npm install
-npm run docs:dev
-```
-
-The documentation will be available at `http://localhost:5173/`
-
-### Online Documentation
-Complete documentation and examples available at [https://richtext.opengis.info](https://richtext.opengis.info)
-
-- [Component documentation](https://richtext.opengis.info/guide/)
-- [API Reference](https://richtext.opengis.info/api/)
-- [Examples](https://richtext.opengis.info/examples/)
-
-## Changelog
-
-Full change log available at [https://richtext.opengis.info/changelog/](https://richtext.opengis.info/changelog/)
-
-Local changelog: [docs/changelog/](docs/changelog/)
-
-
-## Install & Usage
-
-### Install
-
-```bash
-npm i @opengis/richtext
-```
-
-### Usage
-
-#### Complete Editor Example
-```vue
-<template>
-  <VsRichText 
-    v-model="content" 
-    :height="'400px'"
-    :toolbar="toolbarOptions"
-    @update:modelValue="handleContentChange"
-  />
-</template>
-
-<script setup lang="ts">
-import VsRichText from "@opengis/richtext";
-import { ref } from 'vue'
-
-const content = ref('<p>Start typing your content here...</p>')
-
-const toolbarOptions = [
-  'bold',
-  'italic', 
-  'underline',
-  'text_align',
-  'color',
-  'blockquote',
-  'bullet_list',
-  'ordered_list',
-  'codeblock',
-  'link',
-  'table'
-]
-
-const handleContentChange = (newContent: string) => {
-  console.log('Content changed:', newContent)
-}
-</script>
-```
-
-#### Toolbar Controls
-
-- **`bold`** - Жирний текст
-- **`italic`** - Курсив  
-- **`underline`** - Підкреслення
-- **`strike`** - Закреслення
-- **`text_align`** - Вирівнювання тексту
-- **`color`** - Колір тексту
-- **`color_picker`** - Розширений вибір кольору
-- **`blockquote`** - Цитати
-- **`bullet_list`** - Маркований список
-- **`ordered_list`** - Нумерований список
-- **`codeblock`** - Блок коду
-- **`text_more`** - Додаткове форматування
-- **`link`** - Посилання
-- **`table`** - Таблиці
-
-### Register
-
-```ts
-// main.ts
-import VsRichText from '@opengis/richtext'; 
-app.use(VsRichText);
-```
-
-### Style
-
-```html
-<script src="https://cdn.tailwindcss.com"></script>
-```
-
----
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `modelValue` | String | `""` | The HTML content of the editor |
-| `height` | String | `"300px"` | Height of the editor container |
-| `toolbar` | Array | `[...]` | Array of toolbar controls to display |
-
-## Events
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `update:modelValue` | String | Emitted when content changes |
-
-## Styling
-
-The component uses Tailwind CSS classes and can be fully customized with CSS variables:
-
-```css
-.editor-content {
-  /* Customize editor content area */
-}
-
-.editor-toolbar {
-  /* Customize toolbar appearance */
-}
-```
-
-## Contributions
-
-We welcome contributions!
-Feel free to open issues, suggest features, or submit pull requests.
-
-## License
-
-MIT
+# 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** - ваш надійний помічник для створення багатого текстового контенту! 🚀