@shelamkoff/rector 1.0.0

package/dist/plugins/poll/README.md

@@ -0,0 +1,96 @@
+# Poll block plugin
+
+Single- or multiple-choice poll with local results or an application-provided live data source.
+
+## Install and register
+
+```bash
+npm install @shelamkoff/rector
+```
+
+```js
+import { createEditor } from '@shelamkoff/rector'
+import { Poll } from '@shelamkoff/rector/plugins/poll'
+import '@shelamkoff/rector/styles/editor.css'
+
+const editor = createEditor({
+  holder: document.querySelector('#editor'),
+  plugins: [new Poll()],
+})
+```
+
+The registered block type is `poll`. The class is also exported by the complete `@shelamkoff/rector/plugins` preset and can be loaded through `@shelamkoff/rector/plugins/async`.
+
+## Data
+
+```json
+{
+  "pollId": "release-survey",
+  "question": "Which channel should receive the release?",
+  "type": "single",
+  "options": [{ "id": "stable", "text": "Stable" }, { "id": "next", "text": "Next" }],
+  "resultsMode": "afterVote",
+  "initialResults": { "total": 0, "options": [{ "id": "stable", "votes": 0 }, { "id": "next", "votes": 0 }] }
+}
+```
+
+### Field reference
+
+| Field | Required | Meaning and constraints |
+| --- | --- | --- |
+| `pollId` | with `dataSource` | Non-empty application identity used by a remote `dataSource`. It is not generated automatically. Without it a configured source is not loaded and vote submission reports an error. |
+| `question` | yes | Non-blank poll question. |
+| `type` | yes | `single` or `multiple`. |
+| `options` | yes | At least two options. Every option requires a unique non-empty `id` and non-blank `text`; ids remain stable when text or ordering changes. |
+| `resultsMode` | yes | `always`, `afterVote`, or `hidden`; normalization defaults to `always`. |
+| `initialResults` | no | Optional initial or local result snapshot. When present, both `total` and `options` are required. |
+| `initialResults.total` | with `initialResults` | Non-negative integer ballot count used as the percentage denominator before a live source responds or during local voting. |
+| `initialResults.options` | with `initialResults` | Exactly one `{ id, votes }` entry for every author option. Every vote count is a non-negative integer. In a multiple-choice poll their sum may exceed `total`. |
+| `revision` | runtime | Optional opaque server revision. `compareRevisions` defines its ordering when arrival order is insufficient. |
+| `voters`, `votersTotal`, `currentUserVote` | runtime | Optional server result details. Voter ids are required; names, media-policy avatars, and selected option ids are normalized. Live runtime fields are not written into undo/redo history. |
+
+`type` is `single` or `multiple`; `resultsMode` is `always`, `afterVote`, or `hidden`. Option ids are stable document identities. Without `dataSource`, votes update `initialResults` and enter undo/redo. With `dataSource`, live results, voter details, revisions, and the current user vote remain runtime state and are never serialized into editor history.
+
+## Configuration
+
+Every built-in block plugin accepts two style ownership options: `injectStyles?: boolean` defaults to `true`; set it to `false` when the host bundles that plugin's CSS. `css?: string` adds one host-provided stylesheet URL after the plugin default, or acts as the replacement URL when default injection is disabled.
+
+`dataSource?: PollDataSource` supplies required `load` and `vote` callbacks and an optional `subscribe` callback for server-owned results. Every callback receives an `AbortSignal`; `vote` also receives the current `revision`. Every result must contain `total` and one `{ id, votes }` entry for every current option. `total` is the number of ballots and is the percentage denominator; multiple-choice percentages may add up to more than 100%. `compareRevisions?: (next, current) => number` orders opaque revision strings when the backend can deliver updates out of order; without it, unequal revisions follow arrival order. `onError?: (error) => void` observes data-source failures. `maxVoters?: number` limits retained voter details; finite values are rounded down and clamped to zero, while an omitted or non-finite value uses `50`.
+
+```js
+const poll = new Poll({
+  dataSource: {
+    async load({ pollId, signal }) {
+      return api.getPollResults(pollId, { signal })
+    },
+    async vote({ pollId, optionIds, revision, signal }) {
+      return api.submitPollVote(pollId, { optionIds, revision }, { signal })
+    },
+    subscribe({ pollId, signal, onUpdate, onError }) {
+      const connection = api.subscribeToPoll(pollId, { onUpdate, onError })
+      signal.addEventListener('abort', () => connection.close(), { once: true })
+      return () => connection.close()
+    },
+  },
+  compareRevisions: (next, current) => Number(next) - Number(current),
+  onError(error) {
+    console.error('Poll data source failed', error)
+  },
+})
+```
+
+`load` obtains the initial authoritative snapshot. `vote` submits the complete current selection, not a delta, and returns the new authoritative snapshot. `subscribe` sends later snapshots through `onUpdate`; call `onError` for connection errors and return an idempotent cleanup function. The plugin also aborts the supplied signal when the block or editor is disposed. Do not assume revisions are numeric unless the application supplies a numeric `compareRevisions` as in the example.
+
+## Capabilities
+
+Question and option editing; result visibility; option ordering; local voting; cancellable load/vote; live subscriptions; revision ordering; voter summaries; duplicate-submission protection and deterministic cleanup.
+
+## Undo, lifecycle, and styles
+
+User actions exposed by the plugin enter the command pipeline through the supplied `context.mutate()` capability, so each completed action is one undo/redo step. The editor reference-counts the plugin's declared stylesheet URLs. Removing a block calls its cleanup hook; removing the editor calls `destroy()` for every remaining block and then releases shared plugin resources.
+
+Do not remove the editor holder without first calling `editor.destroy()`.
+
+## Document output
+
+Use the matching renderer from `@shelamkoff/rector/renderer/renderers/poll`. The VitePress guide documents configuration, commands and history, extension contracts, document migrations, styling, security, and lifecycle in a sequential form.

package/dist/plugins/poll/README.ru.md

@@ -0,0 +1,97 @@
+# Блочный плагин Poll
+
+Опрос с одиночным или множественным выбором и локальными либо предоставленными приложением актуальными результатами.
+
+## Установка и регистрация
+
+```bash
+npm install @shelamkoff/rector
+```
+
+```js
+import { createEditor } from '@shelamkoff/rector'
+import { Poll } from '@shelamkoff/rector/plugins/poll'
+import '@shelamkoff/rector/styles/editor.css'
+
+const editor = createEditor({
+  holder: document.querySelector('#editor'),
+  plugins: [new Poll()],
+})
+```
+
+Тип блока — `poll`. Класс также экспортируется общей точкой входа `@shelamkoff/rector/plugins` и может загружаться по типу документа через `@shelamkoff/rector/plugins/async`.
+
+## Данные
+
+```json
+{
+  "pollId": "release-survey",
+  "question": "В какой канал отправить уведомление о выпуске?",
+  "type": "single",
+  "options": [{ "id": "stable", "text": "Стабильный" }, { "id": "next", "text": "Следующий" }],
+  "resultsMode": "afterVote",
+  "initialResults": { "total": 0, "options": [{ "id": "stable", "votes": 0 }, { "id": "next", "votes": 0 }] }
+}
+```
+
+### Поля данных
+
+| Поле | Обязательное | Назначение и ограничения |
+| --- | --- | --- |
+| `pollId` | с `dataSource` | Непустой идентификатор приложения для удалённого `dataSource`. Автоматически не создаётся. Без него настроенный источник не загружается, а отправка голоса сообщает об ошибке. |
+| `question` | да | Непустой вопрос опроса. |
+| `type` | да | `single` или `multiple`. |
+| `options` | да | Не менее двух вариантов. Каждому нужны уникальный непустой `id` и непустой `text`; идентификаторы сохраняются при изменении текста и порядка. |
+| `resultsMode` | да | `always`, `afterVote` или `hidden`; при нормализации по умолчанию `always`. |
+| `initialResults` | нет | Необязательный исходный или локальный снимок результатов. Если он передан, поля `total` и `options` обязательны. |
+| `initialResults.total` | с `initialResults` | Неотрицательное целое число бюллетеней, используемое как знаменатель процентов до ответа внешнего источника или при локальном голосовании. |
+| `initialResults.options` | с `initialResults` | Ровно один элемент `{ id, votes }` для каждого варианта. Число голосов должно быть неотрицательным целым. В опросе с множественным выбором их сумма может превышать `total`. |
+| `revision` | во время работы | Необязательная непрозрачная ревизия сервера. `compareRevisions` задаёт порядок, если порядка поступления недостаточно. |
+| `voters`, `votersTotal`, `currentUserVote` | во время работы | Необязательные данные результата сервера. Идентификатор голосующего обязателен; имя, разрешённый политикой медиафайлов аватар и выбранные варианты нормализуются. Текущее состояние сервера не записывается в историю отмены и повтора. |
+
+`type` равен `single` или `multiple`, а `resultsMode` — `always`, `afterVote` или `hidden`. Идентификаторы вариантов устойчивы. Без `dataSource` голосование изменяет `initialResults` и входит в историю. С `dataSource` актуальные результаты, сведения о проголосовавших, ревизия и голос текущего пользователя остаются оперативным состоянием и не попадают в документ или историю.
+
+## Конфигурация
+
+Каждый встроенный блочный плагин принимает два параметра владения стилями: `injectStyles?: boolean` по умолчанию равен `true`; укажите `false`, если приложение само включает CSS этого плагина. `css?: string` добавляет URL таблицы стилей приложения после стандартной, а при отключённой стандартной инъекции служит URL замены.
+
+`dataSource` содержит обязательные методы `load` и `vote` и необязательный `subscribe`; каждый получает `AbortSignal`, а `vote` также получает текущую `revision`. Каждый результат должен содержать `total` и по одному элементу `{ id, votes }` для каждого текущего варианта. `total` — число бюллетеней и знаменатель процентов; при множественном выборе сумма процентов может превышать 100%. `compareRevisions(next, current)` упорядочивает непрозрачные строки ревизий, если сервер может прислать обновления не по порядку; без неё разные ревизии применяются в порядке получения. `onError` наблюдает ошибки источника. `maxVoters` ограничивает число сохраняемых сведений о проголосовавших: конечное значение округляется вниз и ограничивается снизу нулём, а при отсутствии или некорректном значении используется `50`.
+
+```js
+const poll = new Poll({
+  dataSource: {
+    async load({ pollId, signal }) {
+      return api.getPollResults(pollId, { signal })
+    },
+    async vote({ pollId, optionIds, revision, signal }) {
+      return api.submitPollVote(pollId, { optionIds, revision }, { signal })
+    },
+    subscribe({ pollId, signal, onUpdate, onError }) {
+      const connection = api.subscribeToPoll(pollId, { onUpdate, onError })
+      signal.addEventListener('abort', () => connection.close(), { once: true })
+      return () => connection.close()
+    },
+  },
+  compareRevisions: (next, current) => Number(next) - Number(current),
+  onError(error) {
+    console.error('Ошибка источника данных опроса', error)
+  },
+})
+```
+
+`load` получает первый достоверный снимок. `vote` отправляет весь текущий выбор, а не только изменение, и возвращает новый достоверный снимок. `subscribe` передаёт последующие снимки через `onUpdate`; при ошибке соединения вызовите `onError` и верните функцию очистки, которую можно безопасно вызвать повторно. При удалении блока или редактора плагин также прерывает переданный сигнал. Не считайте ревизии числами, если приложение не передало числовую `compareRevisions`, как в примере.
+
+
+## Возможности
+
+Редактирование вопроса и вариантов; настройка видимости результатов; изменение порядка; локальное голосование; прерывание загрузки и отправки голоса через `AbortSignal`; подписка на обновления; упорядочение редакций; сведения о проголосовавших; защита от повторной отправки и освобождение ресурсов.
+
+## История, жизненный цикл и стили
+
+Действия плагина входят в конвейер команд через предоставленный контекст `mutate()`, поэтому одно завершённое действие создаёт один шаг отмены и повтора. Редактор подсчитывает владельцев объявленных URL стилей. Удаление блока вызывает его метод освобождения ресурсов; `editor.destroy()` освобождает оставшиеся блоки и общие ресурсы.
+
+Не удаляйте контейнер редактора до вызова `editor.destroy()`.
+
+## Вывод документа
+
+Используйте фабричную функцию из `@shelamkoff/rector/renderer/renderers/poll`. Последовательное руководство VitePress описывает проверку данных, миграции, разработку расширений, диагностику, безопасность и стили.

package/dist/plugins/poll/index.d.ts

@@ -0,0 +1,134 @@
+import type {} from './locale/keys.js'
+/**
+ * Interactive single- or multiple-choice poll with optional remote result
+ * loading, vote submission, and live result subscriptions.
+ * @extends {BlockPluginAbstract<PollConfig>}
+ */
+export class Poll extends BlockPluginAbstract<PollConfig> {
+    static isTextBlock: boolean;
+    static styles: string[];
+    /**
+     * Create a Poll instance with the supplied consumer configuration.
+     * @param {PollConfig} [config]
+     */
+    constructor(config?: PollConfig);
+    type: string;
+    icon: string;
+    inlineTools: boolean;
+    /**
+     * Return the localized toolbox label for this block.
+     * @returns {string}
+     */
+    get title(): string;
+    /**
+     * Create the editable DOM owned by this block instance.
+     * @param {Record<string, unknown>} data
+     * @param {import('../../core/types.js').BlockMutationContext} context
+     * @returns {HTMLElement}
+     */
+    render(data: Record<string, unknown>, context: import("../../core/types.js").BlockMutationContext): HTMLElement;
+    /**
+     * Serialize the current block DOM into document data.
+     * @param {HTMLElement} element
+     * @returns {PollData}
+     */
+    save(element: HTMLElement): PollData;
+    /**
+     * Check whether serialized data satisfies this block's schema.
+     * @param {Record<string, unknown>} data
+     * @returns {boolean}
+     */
+    validate(data: Record<string, unknown>): boolean;
+    /**
+     * Check whether the block has no meaningful user content.
+     * @param {HTMLElement} element
+     * @returns {boolean}
+     */
+    isEmpty(element: HTMLElement): boolean;
+    /**
+     * Extract neutral text that can initialize another block type.
+     * @param {HTMLElement} element
+     * @returns {{ text: string }}
+     */
+    exportData(element: HTMLElement): {
+        text: string;
+    };
+    /**
+     * Release listeners and resources owned by this block element.
+     * @param {HTMLElement} element
+     * @returns {void}
+     */
+    destroy(element: HTMLElement): void;
+    #private;
+}
+export type PollData = import("../../shared/pollData.js").PollData;
+export type PollResults = import("../../shared/pollData.js").PollResults;
+export type PollDataSource = {
+    /**
+     * Loads the current counts and optional voter summaries for a persisted poll ID.
+     */
+    load: (context: {
+        pollId: string;
+        signal: AbortSignal;
+    }) => Promise<PollResults>;
+    /**
+     * Submits the selected option IDs and returns the authoritative results.
+     */
+    vote: (context: {
+        pollId: string;
+        optionIds: string[];
+        revision?: string;
+        signal: AbortSignal;
+    }) => Promise<PollResults>;
+    /**
+     * Starts live result delivery and optionally returns an idempotent unsubscribe function.
+     */
+    subscribe?: (context: {
+        pollId: string;
+        signal: AbortSignal;
+        onUpdate(results: PollResults): void;
+        onError(error: unknown): void;
+    }) => void | (() => void);
+};
+export type PollConfig = {
+    /**
+     * Backend adapter. Without it votes update the serialized `initialResults` snapshot locally; no remote load, submission, or live subscription occurs.
+     */
+    dataSource?: PollDataSource;
+    /**
+     * Receives rejected load, vote, and subscription errors after the plugin updates its error state.
+     */
+    onError?: (error: unknown) => void;
+    /**
+     * Maximum number of voter summaries retained and rendered. Finite values are rounded down and clamped to zero; omitted or non-finite values use 50.
+     */
+    maxVoters?: number;
+    /**
+     * Orders opaque backend revisions. Return a positive number when `next` is newer, zero when equal, and a negative number when stale.
+     */
+    compareRevisions?: (next: string, current: string) => number;
+    /**
+     * Whether the editor should load the built-in poll stylesheet.
+     */
+    injectStyles?: boolean;
+    /**
+     * Additional stylesheet URL, or the replacement URL when `injectStyles` is `false`.
+     */
+    css?: string;
+};
+export type PollState = {
+    data: PollData;
+    runtime: PollResults;
+    selected: Set<string>;
+    hasVoted: boolean;
+    loading: boolean;
+    submitting: boolean;
+    error: boolean;
+    connectionVersion: number;
+    loadVersion: number;
+    voteVersion: number;
+    abortController: AbortController | null;
+    unsubscribe: (() => void) | null;
+    context: import("../../core/types.js").BlockMutationContext;
+};
+import { BlockPluginAbstract } from '../BlockPluginAbstract.js';