@shelamkoff/rector 1.0.0

package/dist/inline-plugins/mention/README.ru.md

@@ -0,0 +1,97 @@
+# Внутристрочный плагин упоминаний
+
+Поиск сущности по символу активации с клавиатурной навигацией, постраничной загрузкой по курсору, пользовательским отображением результатов и устойчивыми идентификаторами виджетов.
+
+## Регистрация в редакторе
+
+```js
+import { createEditor } from '@shelamkoff/rector'
+import { Paragraph } from '@shelamkoff/rector/plugins/paragraph'
+import { createMentionPlugin } from '@shelamkoff/rector/inline-plugins/mention'
+import '@shelamkoff/rector/styles/editor.css'
+
+const mention = createMentionPlugin({
+  async searchFunction(query, nextPageUrl, { signal }) {
+    const url = nextPageUrl ?? `/api/people?q=${encodeURIComponent(query)}`
+    const response = await fetch(url, { signal })
+    if (!response.ok) throw new Error(`Ошибка поиска упоминания: ${response.status}`)
+    return response.json()
+  },
+})
+
+const editor = createEditor({
+  holder: document.querySelector('#editor'),
+  plugins: [new Paragraph()],
+  inlinePlugins: [mention],
+})
+```
+
+Тип плагина — `mention`. Символ активации должен состоять ровно из одной кодовой точки Юникода. Его ввод в начале текстового узла либо после обычного или неразрывного пробела открывает поиск. В `query` символ активации не входит. Стрелки перемещают выбранный результат, `Enter` или `Tab` подтверждают его, `Escape` закрывает окно, а прокрутка к концу списка запрашивает следующую страницу по `nextPageUrl`, если приложение её предоставило.
+
+## Контракт поиска
+
+`searchFunction` возвращает `MentionItem[]` либо `{ items: MentionItem[], nextPageUrl?: string | null }`:
+
+```ts
+interface MentionItem {
+  id: string | number
+  name: string
+  avatar?: string
+  details?: string
+  [applicationField: string]: unknown
+}
+```
+
+Для первой страницы аргумент `nextPageUrl` равен `null`. Для следующих страниц это непрозрачный курсор, ранее возвращённый приложением. Передавайте полученный `AbortSignal` сетевому клиенту или источнику данных. Новый запрос, закрытие окна или `editor.destroy()` прерывают текущий сигнал; устаревший ответ игнорируется даже тогда, когда сам клиент не умеет отменять работу.
+
+Отсутствующий `searchFunction` допустим, но список всегда будет пустым. Ошибки, не являющиеся прерыванием, выводятся через `console.warn` и не заменяют результаты текущего сеанса.
+
+## Параметры
+
+| Параметр | Тип | Значение по умолчанию и поведение |
+| --- | --- | --- |
+| `trigger` | `string` | `@`. Ровно одна кодовая точка Юникода, которая запускает поиск и отображается перед именем; другое значение приводит к ошибке при создании плагина. Поэтому составные графемы из нескольких кодовых точек, например флаг, отклоняются. |
+| `searchFunction` | `MentionSearchFunction \| null` | `null`; без источника подсказки отсутствуют. |
+| `debounceDelay` | `number` | `300` мс для непустого запроса первой страницы. Пустой запрос и следующие страницы выполняются без задержки. |
+| `noResultsText` | `string` | Сообщение текущего языка (`Ничего не найдено` для русского). |
+| `dropdownClass` | `string` | Пустая строка. Дополнительный класс корневого элемента окна. |
+| `onMentionSelect` | `({ id, name }) => void` | Не задан. Наблюдает подтверждённый выбор; ошибка обработчика не отменяет вставку. |
+| `renderItem` | `(item, index, isActive) => HTMLElement \| null` | Стандартная строка с необязательными аватаром и пояснением. Верните `null` или `undefined`, чтобы использовать её. |
+| `renderNoResults` | `(text) => HTMLElement \| null` | Стандартная строка отсутствия результатов. |
+| `renderLoading` | `() => HTMLElement \| null` | Стандартная строка загрузки. |
+
+Дополнительные поля элемента доступны только `renderItem`. Они не сохраняются и не передаются в `onMentionSelect`.
+
+Каждая функция отображения должна возвращать новый, ещё не добавленный в DOM элемент `HTMLElement`. К пользовательской строке результата Rector добавляет классы списка, индекс, идентификатор и атрибуты доступности, необходимые для клавиатурной навигации. Пользовательские строки отсутствия результата и загрузки также помечаются как служебное содержимое с уведомлением вспомогательных технологий. Значение `null`, `undefined` или результат другого типа включает стандартную строку.
+
+## Сохраняемые данные и редактирование
+
+Текстовое поле содержит `{{widgetId}}`, а карта `inline` блока хранит только устойчивый идентификатор сущности и отображаемое имя:
+
+```json
+{
+  "text": "Ответственный: {{w_owner}}",
+  "inline": {
+    "w_owner": {
+      "type": "mention",
+      "data": { "id": "42", "name": "Ада Лавлейс" }
+    }
+  }
+}
+```
+
+Сохраняемый `id` преобразуется в строку. `onMentionSelect` получает исходный строковый или числовой идентификатор результата. Редактирование существующей плашки запускает новый поиск. Выбор результата атомарно обновляет виджет; выход без выбора превращает изменённую плашку в обычный видимый текст. Если автосохранение происходит во время незавершённого поиска, временная плашка также сохраняется как текст, а не как некорректное упоминание.
+
+## История, жизненный цикл и стили
+
+Первая вставка или замена существующего упоминания создаёт один шаг отмены и повтора. Текст запроса, перемещение по результатам, состояние загрузки, открытие и закрытие окна являются временным состоянием интерфейса и не создают команд.
+
+Плагин владеет одним окном, обработчиками документа и окна браузера, таймером задержки, контроллером запросов и таблицей стилей с подсчётом владельцев. `editor.destroy()` освобождает все эти ресурсы. Для каждого редактора создавайте отдельный экземпляр плагина: повторное подключение одного экземпляра отклоняется.
+
+Сохранённая плашка использует `.oe-ip--mention`, а окно подсказок — `.oe-mention-dropdown` и его дочерние классы. Адрес `avatar` проходит общую политику медиафайлов, а стандартные строки записывают имя и пояснение безопасными текстовыми операциями DOM.
+
+## Отображение документа
+
+Передайте `createMentionWidget()` в массив `inlinePlugins` конструктора `EditorRenderer`. Эта облегчённая фабрика содержит только преобразование данных виджета в DOM и обратно; поиск, окно и обработчики редактора в неё не входят. Если редактор использует нестандартный символ активации, передайте тот же символ фабрике рендерера, например `createMentionWidget('#')`. Символ относится к настройкам отображения и не повторяется в данных каждого сохранённого виджета.
+
+Последовательное руководство VitePress описывает полный контракт внутристрочного виджета, формат хранения, границы истории, создание пользовательского плагина, безопасность и освобождение ресурсов.

package/dist/inline-plugins/mention/index.d.ts

@@ -0,0 +1,110 @@
+import type { InlinePlugin } from '../../core/types.js'
+import type { InlineWidget, InlinePluginLike } from '../../renderer/types.js'
+
+/**
+ * A single search-result entry for the mention dropdown.
+ * Mirrors the shape of `@shelamkoff/mentionjs` MentionItem so existing
+ * call-sites can migrate with minimal changes.
+ */
+export interface MentionItem {
+  id: string | number
+  name: string
+  /** Optional avatar URL. Falls back to an initials-filled placeholder. */
+  avatar?: string
+  /** Optional secondary line shown under the name. */
+  details?: string
+  /** Extra fields remain available to custom result renderers. They are not persisted or passed to `onMentionSelect`. */
+  [key: string]: unknown
+}
+
+/**
+ * Result of a single `searchFunction` call. Either a bare array of items
+ * or an object with optional pagination cursor.
+ */
+export interface MentionSearchResult {
+  items: MentionItem[]
+  nextPageUrl?: string | null
+}
+
+export interface MentionSearchContext {
+  /** Aborted when a newer query starts, the popup closes, or the plugin is destroyed. */
+  signal: AbortSignal
+}
+
+export type MentionSearchFunction = (
+  query: string,
+  nextPageUrl: string | null,
+  context: MentionSearchContext,
+) => Promise<MentionSearchResult | MentionItem[]>
+
+export type MentionRenderItem = (
+  data: MentionItem,
+  index: number,
+  isActive: boolean,
+) => HTMLElement | null | undefined
+
+export type MentionRenderNoResults = (
+  noResultsText: string,
+) => HTMLElement | null | undefined
+
+export type MentionRenderLoading = () => HTMLElement | null | undefined
+
+export interface MentionPluginOptions {
+  /** Exactly one Unicode code point that activates and prefixes a mention. Default: '@'. */
+  trigger?: string
+  /** Async callback that returns suggestions for a query. Without it the dropdown is empty. */
+  searchFunction?: MentionSearchFunction | null
+  /** Debounce window between keystroke and `searchFunction` call. */
+  debounceDelay?: number
+  /** Fallback text when no results match. Defaults to the i18n string. */
+  noResultsText?: string
+  /** Extra class appended to the dropdown root element. */
+  dropdownClass?: string
+  /** Fires when a user commits a mention (keyboard or click). */
+  onMentionSelect?: ((data: { id: string | number; name: string }) => void) | null
+  /** Custom renderer for list items. Return an HTMLElement or null to fall back. */
+  renderItem?: MentionRenderItem | null
+  /** Custom renderer for the no-results row. */
+  renderNoResults?: MentionRenderNoResults | null
+  /** Custom renderer for the loading row. */
+  renderLoading?: MentionRenderLoading | null
+}
+
+/**
+ * Factory: build a mention inline plugin suitable for `createEditor({ inlinePlugins: [...] })`.
+ *
+ * The plugin listens for the trigger character (default `@`) via the editor's
+ * built-in `TriggerManager`, opens a searchable dropdown, and commits the
+ * selected user as a Rector inline widget:
+ *
+ *   <span data-inline-plugin="mention" data-value="<id>"
+ *         class="oe-ip oe-ip--mention">@Name</span>
+ *
+ * The widget survives paragraph save/render via the shared sanitize allowlist,
+ * and is restored by the document renderer using the same widget contract.
+ */
+export function createMentionPlugin(options?: MentionPluginOptions): InlinePlugin
+
+/**
+ * The `data` shape carried in `InlineWidget<'mention'>.data` — the
+ * plugin-specific payload written during save and read during load.
+ *
+ * `id`   — the committed user id (mirrors `data-value` on the span).
+ * `name` — display name, WITHOUT the trigger character (marshal strips `@`).
+ */
+export interface MentionWidgetData extends Record<string, unknown> {
+  id: string
+  name: string
+}
+
+/** Concrete inline widget type produced by mention saves. */
+export type MentionWidget = InlineWidget<'mention', MentionWidgetData>
+
+/**
+ * Renderer-side mention widget — just `createWidget` + `getData` + `type`.
+ * Pass to `RendererConfig.inlinePlugins` so the renderer can rehydrate
+ * mention placeholders into their display pills without dragging in the
+ * full editor runtime (dropdown UI, trigger manager, search pipeline).
+ * Pass the same trigger used by `createMentionPlugin()` when it is not `@`.
+ */
+export function createMentionWidget(trigger?: string): InlinePluginLike