@notehub.md/cli 0.1.9 → 0.1.11

package/templates/docs/ru/04-widgets.md

@@ -0,0 +1,289 @@
+# Виджеты (Порталы)
+
+Порталы — это кастомные React-компоненты, которые рендерятся инлайн в редакторе, заменяя совпадающие текстовые паттерны.
+
+## Как работают порталы
+
+1. Вы определяете **regex-паттерн**, который ищет текст в документе
+2. Вы предоставляете **React-компонент** для рендеринга каждого совпадения
+3. Notehub заменяет совпадающий текст вашим компонентом в **режиме просмотра**
+4. Когда курсор входит в совпадение, переключается в **режим редактирования** (показывает исходный текст)
+
+```
+Режим просмотра:  [████████░░] 80%     ← Ваш отрендеренный компонент
+Режим редактирования: [progress:80]   ← Исходный текст виден когда курсор внутри
+```
+
+## Регистрация портала
+
+Используйте API `editor:register-portal`:
+
+```typescript
+await ctx.invokeApi('editor:register-portal', {
+    id: 'unique-id',           // Уникальный идентификатор
+    regex: /regex-pattern/g,   // Паттерн для поиска (ДОЛЖЕН иметь флаг 'g')
+    component: ReactComponent  // Компонент для рендеринга
+});
+```
+
+## Пропсы компонента
+
+Ваш компонент получает массив результатов regex:
+
+```typescript
+interface WidgetProps {
+    match: RegExpExecArray;
+}
+```
+
+Массив `match` содержит:
+- `match[0]` — Полная совпавшая строка
+- `match[1]`, `match[2]`, ... — Захваченные группы
+
+## Полный пример: Прогресс-бар
+
+```typescript
+import { NotehubPlugin, PluginContext } from '@notehub/api';
+import React from 'react';
+
+// Компонент виджета
+const ProgressBar: React.FC<{ match: RegExpExecArray }> = ({ match }) => {
+    const percentage = parseInt(match[1], 10);
+    
+    return (
+        <span style={{
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: '8px',
+            padding: '2px 8px',
+            background: 'var(--nh-bg-surface)',
+            borderRadius: '4px',
+        }}>
+            <span style={{
+                width: '100px',
+                height: '8px',
+                background: 'var(--nh-bg-secondary)',
+                borderRadius: '4px',
+                overflow: 'hidden',
+            }}>
+                <span style={{
+                    width: `${percentage}%`,
+                    height: '100%',
+                    background: 'var(--nh-accent-primary)',
+                    display: 'block',
+                    borderRadius: '4px',
+                    transition: 'width 0.3s ease',
+                }} />
+            </span>
+            <span style={{ fontSize: '12px', color: 'var(--nh-text-muted)' }}>
+                {percentage}%
+            </span>
+        </span>
+    );
+};
+
+// Плагин
+export default class ProgressBarPlugin extends NotehubPlugin {
+    async onload(ctx: PluginContext): Promise<void> {
+        // Совпадение: [progress:XX] где XX — число
+        await ctx.invokeApi('editor:register-portal', {
+            id: 'progress-bar',
+            regex: /\[progress:(\d+)\]/g,
+            component: ProgressBar
+        });
+        
+        await ctx.invokeApi('logger:info', 'ProgressBar', 'Портал зарегистрирован');
+    }
+    
+    async onunload(): Promise<void> {
+        // Портал автоматически отменяет регистрацию!
+    }
+}
+```
+
+**Использование в документах:**
+```markdown
+Завершенность проекта: [progress:75]
+```
+
+---
+
+## Пример: Кликабельная кнопка
+
+```typescript
+const ButtonWidget: React.FC<{ match: RegExpExecArray }> = ({ match }) => {
+    const label = match[1];
+    const action = match[2];
+    
+    const handleClick = async () => {
+        console.log(`Кнопка нажата: ${action}`);
+    };
+    
+    return (
+        <button
+            onClick={handleClick}
+            style={{
+                background: 'var(--nh-accent-primary)',
+                color: 'var(--nh-button-text, #fff)',
+                border: 'none',
+                borderRadius: '4px',
+                padding: '4px 12px',
+                cursor: 'pointer',
+                fontSize: 'inherit',
+            }}
+        >
+            {label}
+        </button>
+    );
+};
+
+// Регистрация
+await ctx.invokeApi('editor:register-portal', {
+    id: 'btn-widget',
+    regex: /\[btn:([^\]:]+):([^\]]+)\]/g,
+    component: ButtonWidget
+});
+```
+
+**Использование:**
+```markdown
+Нажмите сюда: [btn:Отправить:action-submit]
+```
+
+---
+
+## Пример: Статус-бейдж
+
+```typescript
+const StatusBadge: React.FC<{ match: RegExpExecArray }> = ({ match }) => {
+    const status = match[1].toLowerCase();
+    
+    const colors: Record<string, { bg: string; text: string }> = {
+        done: { bg: '#22c55e20', text: '#22c55e' },
+        'in-progress': { bg: '#f59e0b20', text: '#f59e0b' },
+        todo: { bg: '#6b728020', text: '#6b7280' },
+    };
+    
+    const style = colors[status] || colors.todo;
+    
+    return (
+        <span style={{
+            padding: '2px 8px',
+            borderRadius: '12px',
+            fontSize: '12px',
+            fontWeight: 500,
+            background: style.bg,
+            color: style.text,
+        }}>
+            {match[1]}
+        </span>
+    );
+};
+
+await ctx.invokeApi('editor:register-portal', {
+    id: 'status-badge',
+    regex: /\[status:([^\]]+)\]/g,
+    component: StatusBadge
+});
+```
+
+**Использование:**
+```markdown
+Задача 1 [status:Done]
+Задача 2 [status:In-Progress]
+Задача 3 [status:TODO]
+```
+
+---
+
+## Лучшие практики Regex
+
+### 1. Всегда используйте глобальный флаг (`g`)
+
+```typescript
+// ✅ Хорошо
+/\[progress:(\d+)\]/g
+
+// ❌ Плохо — не найдет множественные вхождения
+/\[progress:(\d+)\]/
+```
+
+### 2. Используйте группы захвата для динамического контента
+
+```typescript
+// Захватывает две группы: label и value
+/\[meter:([^:]+):(\d+)\]/g
+// match[1] = label
+// match[2] = value
+```
+
+### 3. Экранируйте специальные символы
+
+```typescript
+// Совпадение [!note] — скобки нужно экранировать
+/\[!note\]/g
+```
+
+### 4. Будьте конкретны, чтобы избежать ложных совпадений
+
+```typescript
+// ✅ Хорошо — конкретный паттерн
+/\[progress:(\d{1,3})\]/g
+
+// ❌ Плохо — слишком жадный
+/\[.*\]/g  // Совпадает со ВСЕМ контентом в скобках!
+```
+
+---
+
+## Советы по стилизации
+
+### Используйте CSS-переменные
+
+Используйте цвета темы для согласованной стилизации:
+
+```typescript
+style={{
+    background: 'var(--nh-bg-surface)',
+    color: 'var(--nh-text-primary)',
+    border: '1px solid var(--nh-border-subtle)',
+}}
+```
+
+Доступные CSS-переменные:
+- `--nh-bg-main`, `--nh-bg-sidebar`, `--nh-bg-surface`
+- `--nh-text-primary`, `--nh-text-secondary`, `--nh-text-muted`
+- `--nh-accent-primary`, `--nh-accent-secondary`
+- `--nh-border-accent`, `--nh-border-subtle`
+
+### Держите это инлайн
+
+Виджеты рендерятся встроенными в текст. Используйте `display: inline-flex` или `inline-block`:
+
+```typescript
+style={{
+    display: 'inline-flex',
+    alignItems: 'center',
+    verticalAlign: 'middle',
+}}
+```
+
+---
+
+## Отмена регистрации виджетов
+
+Порталы **автоматически отменяют регистрацию** при выгрузке вашего плагина.
+
+Для ручной отмены:
+
+```typescript
+await ctx.invokeApi('editor:unregister-portal', 'my-portal-id');
+```
+
+---
+
+## Следующие шаги
+
+- Добавьте **[Настройки](05-settings.md)** для конфигурации ваших виджетов
+- Изучите **[Контекстные меню](06-context-menu.md)**
+- Смотрите **[Полные примеры](07-examples.md)**

package/templates/docs/ru/05-settings.md

@@ -0,0 +1,303 @@
+# Интеграция настроек
+
+Добавление параметров конфигурации в ваш плагин через Settings API.
+
+## Структура настроек
+
+Настройки организованы в иерархию:
+
+```
+Модальное окно настроек
+└── Вкладка (например, "Мой плагин")
+    └── Группа (например, "Внешний вид")
+        └── Элемент (например, "Включить темный режим")
+```
+
+## Шаг 1: Регистрация вкладки
+
+```typescript
+await ctx.invokeApi('settings:register-tab', {
+    id: 'my-plugin',            // Уникальный идентификатор
+    label: 'Мой плагин',        // Отображаемое имя
+    icon: 'puzzle',             // Имя иконки Lucide (kebab-case)
+    order: 100                  // Позиция (меньше = первее)
+});
+```
+
+## Шаг 2: Регистрация группы
+
+```typescript
+await ctx.invokeApi('settings:register-group', {
+    id: 'my-plugin-general',    // Уникальный идентификатор
+    tabId: 'my-plugin',         // ID родительской вкладки
+    label: 'Основные',          // Отображаемое имя
+    order: 0                    // Позиция внутри вкладки
+});
+```
+
+## Шаг 3: Регистрация элементов
+
+### Toggle (Булевый переключатель)
+
+```typescript
+await ctx.invokeApi('settings:register-item', {
+    key: 'my-plugin.enabled',
+    type: 'toggle',
+    label: 'Включить плагин',
+    description: 'Включение или выключение плагина',
+    groupId: 'my-plugin-general',
+    order: 0,
+    defaultValue: true
+});
+```
+
+### Text (Текстовое поле)
+
+```typescript
+await ctx.invokeApi('settings:register-item', {
+    key: 'my-plugin.prefix',
+    type: 'text',
+    label: 'Кастомный префикс',
+    description: 'Текст для добавления перед элементами',
+    placeholder: 'Введите префикс...',
+    groupId: 'my-plugin-general',
+    order: 1,
+    defaultValue: ''
+});
+```
+
+### Number (Числовое поле)
+
+```typescript
+await ctx.invokeApi('settings:register-item', {
+    key: 'my-plugin.max-items',
+    type: 'number',
+    label: 'Максимум элементов',
+    description: 'Ограничение количества отображаемых элементов',
+    groupId: 'my-plugin-general',
+    order: 2,
+    min: 1,
+    max: 100,
+    step: 1,
+    defaultValue: 10
+});
+```
+
+### Select (Выпадающий список)
+
+```typescript
+await ctx.invokeApi('settings:register-item', {
+    key: 'my-plugin.theme',
+    type: 'select',
+    label: 'Тема виджета',
+    description: 'Выбор визуального стиля',
+    groupId: 'my-plugin-general',
+    order: 3,
+    options: [
+        { label: 'По умолчанию', value: 'default' },
+        { label: 'Компактный', value: 'compact' },
+        { label: 'Минимальный', value: 'minimal' }
+    ],
+    defaultValue: 'default'
+});
+```
+
+### Color (Выбор цвета)
+
+```typescript
+await ctx.invokeApi('settings:register-item', {
+    key: 'my-plugin.accent-color',
+    type: 'color',
+    label: 'Акцентный цвет',
+    description: 'Основной цвет для выделений',
+    groupId: 'my-plugin-general',
+    order: 4,
+    defaultValue: '#3b82f6'
+});
+```
+
+---
+
+## Чтение значений настроек
+
+Используйте API `config:get` для чтения настроек:
+
+```typescript
+const isEnabled = await ctx.invokeApi<boolean>('config:get', 'my-plugin.enabled', true);
+const prefix = await ctx.invokeApi<string>('config:get', 'my-plugin.prefix', '');
+const maxItems = await ctx.invokeApi<number>('config:get', 'my-plugin.max-items', 10);
+const theme = await ctx.invokeApi<string>('config:get', 'my-plugin.theme', 'default');
+const color = await ctx.invokeApi<string>('config:get', 'my-plugin.accent-color', '#3b82f6');
+```
+
+---
+
+## Полный пример
+
+```typescript
+import { NotehubPlugin, PluginContext } from '@notehub/api';
+
+export default class ConfigurablePlugin extends NotehubPlugin {
+    async onload(ctx: PluginContext): Promise<void> {
+        // Регистрация вкладки настроек
+        await ctx.invokeApi('settings:register-tab', {
+            id: 'my-plugin',
+            label: 'Мой плагин',
+            icon: 'settings-2',
+            order: 100
+        });
+        
+        // Регистрация группы
+        await ctx.invokeApi('settings:register-group', {
+            id: 'my-plugin-appearance',
+            tabId: 'my-plugin',
+            label: 'Внешний вид',
+            order: 0
+        });
+        
+        // Регистрация элементов
+        await ctx.invokeApi('settings:register-items', [
+            {
+                key: 'my-plugin.show-icons',
+                type: 'toggle',
+                label: 'Показывать иконки',
+                groupId: 'my-plugin-appearance',
+                order: 0,
+                defaultValue: true
+            },
+            {
+                key: 'my-plugin.icon-size',
+                type: 'select',
+                label: 'Размер иконок',
+                groupId: 'my-plugin-appearance',
+                order: 1,
+                options: [
+                    { label: 'Маленький', value: 16 },
+                    { label: 'Средний', value: 24 },
+                    { label: 'Большой', value: 32 }
+                ],
+                defaultValue: 24
+            }
+        ]);
+        
+        // Использование значений
+        const showIcons = await ctx.invokeApi<boolean>('config:get', 'my-plugin.show-icons', true);
+        const iconSize = await ctx.invokeApi<number>('config:get', 'my-plugin.icon-size', 24);
+        
+        await ctx.invokeApi('logger:info', 'MyPlugin', 
+            `Настройки: showIcons=${showIcons}, iconSize=${iconSize}`);
+    }
+    
+    async onunload(): Promise<void> {
+        // Элементы настроек автоматически удаляются!
+    }
+}
+```
+
+---
+
+## Пакетная регистрация
+
+Для множества элементов используйте пакетные API:
+
+```typescript
+// Регистрация нескольких вкладок
+await ctx.invokeApi('settings:register-tabs', [
+    { id: 'tab1', label: 'Вкладка 1', icon: 'star', order: 0 },
+    { id: 'tab2', label: 'Вкладка 2', icon: 'heart', order: 1 }
+]);
+
+// Регистрация нескольких групп
+await ctx.invokeApi('settings:register-groups', [
+    { id: 'group1', tabId: 'tab1', label: 'Группа 1', order: 0 },
+    { id: 'group2', tabId: 'tab1', label: 'Группа 2', order: 1 }
+]);
+
+// Регистрация нескольких элементов
+await ctx.invokeApi('settings:register-items', [/* массив элементов */]);
+```
+
+---
+
+## Кастомное представление настроек
+
+Для сложного UI настроек зарегистрируйте кастомный React-компонент:
+
+```typescript
+const MyCustomSettings: React.FC = () => {
+    return (
+        <div>
+            <h2>Кастомный UI настроек</h2>
+            {/* Ваш кастомный интерфейс */}
+        </div>
+    );
+};
+
+await ctx.invokeApi('settings:register-custom-view', {
+    tabId: 'my-plugin',
+    view: MyCustomSettings
+});
+```
+
+---
+
+## Программное управление
+
+```typescript
+// Открыть модальное окно настроек
+await ctx.invokeApi('settings:open');
+
+// Закрыть модальное окно настроек
+await ctx.invokeApi('settings:close');
+
+// Переключить модальное окно настроек
+await ctx.invokeApi('settings:toggle');
+```
+
+---
+
+## Определения типов
+
+```typescript
+interface SettingsTabDef {
+    id: string;          // Уникальный идентификатор
+    label: string;       // Отображаемый текст
+    icon: string;        // Имя иконки Lucide
+    order: number;       // Порядок сортировки
+}
+
+interface SettingsGroupDef {
+    id: string;          // Уникальный идентификатор
+    tabId: string;       // ID родительской вкладки
+    label: string;       // Отображаемый текст
+    order: number;       // Порядок сортировки
+}
+
+interface SettingsItemDef {
+    key: string;         // Ключ конфига (например, 'my-plugin.option')
+    type: 'toggle' | 'text' | 'number' | 'select' | 'color';
+    label: string;       // Отображаемый текст
+    description?: string;
+    groupId: string;     // ID родительской группы
+    order: number;       // Порядок сортировки
+    defaultValue?: unknown;
+    
+    // Для 'text'
+    placeholder?: string;
+    
+    // Для 'number'
+    min?: number;
+    max?: number;
+    step?: number;
+    
+    // Для 'select'
+    options?: Array<{ label: string; value: unknown }>;
+}
+```
+
+---
+
+## Следующие шаги
+
+- Изучите интеграцию **[Контекстных меню](06-context-menu.md)**
+- Смотрите **[Полные примеры](07-examples.md)**