@shelamkoff/rector 1.0.0

package/dist/renderer/renderers/person/index.js

@@ -0,0 +1,213 @@
+// @ts-check
+import { Carousel, createSwipe, carouselStylesUrl } from '@shelamkoff/carousel'
+import { resolvePath } from '../../../shared/resolvePath.js'
+import { setSafeUrlAttribute } from '../../../shared/sanitize/sanitizeUrl.js'
+
+const styles = resolvePath('./styles.css', import.meta.url)
+const carouselStyles = carouselStylesUrl
+
+const ICON_LEFT = '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M15 6l-6 6l6 6"/></svg>'
+const ICON_RIGHT = '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M9 6l6 6l-6 6"/></svg>'
+
+/** @type {Record<string, string>} */
+const SOCIAL_ICONS = {
+    website: `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M2 12h20"/><path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"/></svg>`,
+    twitter: `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 4l11.733 16h4.267l-11.733-16z"/><path d="M4 20l6.768-6.768m2.46-2.46l6.772-6.772"/></svg>`,
+    github: `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 19c-4.3 1.4-4.3-2.5-6-3m12 5v-3.5c0-1 .1-1.4-.5-2 2.8-.3 5.5-1.4 5.5-6a4.6 4.6 0 0 0-1.3-3.2 4.2 4.2 0 0 0-.1-3.2s-1.1-.3-3.5 1.3a12.3 12.3 0 0 0-6.2 0C6.5 2.8 5.4 3.1 5.4 3.1a4.2 4.2 0 0 0-.1 3.2A4.6 4.6 0 0 0 4 9.5c0 4.6 2.7 5.7 5.5 6-.6.6-.6 1.2-.5 2V21"/></svg>`,
+    telegram: `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 10l-4 4l6 6l4-16l-18 7l4 2l2 6l3-4"/></svg>`,
+    linkedin: `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="4" y="4" width="16" height="16" rx="2"/><path d="M8 11v5"/><path d="M8 8v.01"/><path d="M12 16v-5"/><path d="M16 16v-3a2 2 0 1 0-4 0"/></svg>`,
+}
+
+/**
+ * Person/author card block renderer — supports multi-person with carousel
+ * @param {string} classPrefix
+ * @param {Record<string, import('../../../shared/localeTypes').LocaleValue>} locale
+ * @returns {import('../../types').BlockRenderer<import('../../types').PersonBlock>}
+ */
+export function createPersonRenderer(classPrefix, /** @type {Record<string, import('../../../shared/localeTypes').LocaleValue>} */ locale) {
+    const t = (/** @type {string} */ key, /** @type {string} */ fallback) => {
+        const value = locale?.[key]
+        return typeof value === 'string' ? value : fallback
+    }
+    const p = `${classPrefix}-person`
+    const mounted = new WeakMap()
+
+
+    return {
+        type: 'person',
+        styles: [styles, carouselStyles],
+
+        /**
+         * @param {import('../../types').PersonBlock} block
+         * @param {import('../../types').InlineParser} parseInline
+         * @returns {HTMLElement}
+         */
+        render(block, parseInline) {
+            const persons = /** @type {any[]} */ (block.data.persons || [])
+
+            const wrapper = document.createElement('div')
+            wrapper.className = p
+            /** @type {{ observer: ResizeObserver | null, carousel: Carousel | null }} */
+            const resources = { observer: null, carousel: null }
+            mounted.set(wrapper, resources)
+
+
+            if (persons.length <= 1) {
+                const person = persons[0] || block.data
+                wrapper.appendChild(renderCard(person, parseInline, p, t))
+            } else {
+                const carouselContainer = document.createElement('div')
+                carouselContainer.className = `${p}__carousel`
+                wrapper.appendChild(carouselContainer)
+
+                // Build slides from persons
+                const slides = persons.map(person => ({
+                    content: () => renderCard(person, parseInline, p, t),
+                }))
+
+                // Measure once mounted to decide if carousel is needed
+                const CARD_W = 300
+                const GAP = 16
+                const ro = new ResizeObserver(() => {
+                    if (!carouselContainer.offsetWidth) return
+                    ro.disconnect()
+
+                    const totalW = persons.length * CARD_W + (persons.length - 1) * GAP
+
+                    if (totalW <= carouselContainer.offsetWidth) {
+                        // All fit — simple flex row
+                        const list = document.createElement('div')
+                        list.className = `${p}__list`
+                        for (const person of persons) {
+                            list.appendChild(renderCard(person, parseInline, p, t))
+                        }
+                        carouselContainer.appendChild(list)
+                        return
+                    }
+
+                    // Overflow — init Carousel
+                    const slidesPerView = Math.max(1, Math.floor(carouselContainer.offsetWidth / (CARD_W + GAP)))
+                    const carousel = new Carousel(carouselContainer, slides, {
+                        slidesPerView,
+                        gap: GAP,
+                        loop: persons.length > slidesPerView,
+                        plugins: [createSwipe()],
+                    })
+                    resources.carousel = carousel
+
+                    // External nav below carousel (not inside viewport)
+                    const nav = document.createElement('div')
+                    nav.className = `${p}__nav`
+                    const prevBtn = document.createElement('button')
+                    prevBtn.type = 'button'
+                    prevBtn.className = `${p}__nav-btn`
+                    prevBtn.innerHTML = ICON_LEFT
+                    prevBtn.setAttribute('aria-label', t('renderer.person.previous', 'Previous person'))
+                    prevBtn.querySelector('svg')?.setAttribute('aria-hidden', 'true')
+                    prevBtn.addEventListener('click', () => carousel.prev())
+                    const nextBtn = document.createElement('button')
+                    nextBtn.type = 'button'
+                    nextBtn.className = `${p}__nav-btn`
+                    nextBtn.innerHTML = ICON_RIGHT
+                    nextBtn.setAttribute('aria-label', t('renderer.person.next', 'Next person'))
+                    nextBtn.querySelector('svg')?.setAttribute('aria-hidden', 'true')
+                    nextBtn.addEventListener('click', () => carousel.next())
+                    nav.appendChild(prevBtn)
+                    nav.appendChild(nextBtn)
+                    wrapper.appendChild(nav)
+                })
+                resources.observer = ro
+                ro.observe(carouselContainer)
+            }
+
+            return wrapper
+        },
+        destroy(element) {
+            const resources = mounted.get(element)
+            if (!resources) return
+            resources.observer?.disconnect()
+            resources.carousel?.destroy()
+            mounted.delete(element)
+        },
+    }
+}
+
+/**
+ * @param {any} person
+ * @param {import('../../types').InlineParser} parseInline
+ * @param {string} p
+ * @param {(key: string, fallback: string) => string} t
+ * @returns {HTMLElement}
+ */
+function renderCard(person, parseInline, p, t) {
+    const { avatar, name, role, bio, links } = person
+
+    const card = document.createElement('div')
+    card.className = `${p}__card`
+
+    if (avatar) {
+        const avatarWrap = document.createElement('div')
+        avatarWrap.className = `${p}__avatar-wrap`
+        const img = document.createElement('img')
+        img.className = `${p}__avatar-img`
+        setSafeUrlAttribute(img, 'src', avatar, 'media')
+        img.alt = name || ''
+        img.loading = 'lazy'
+        avatarWrap.appendChild(img)
+        card.appendChild(avatarWrap)
+    }
+
+    const info = document.createElement('div')
+    info.className = `${p}__info`
+
+    if (name) {
+        const nameEl = document.createElement('div')
+        nameEl.className = `${p}__name`
+        nameEl.appendChild(parseInline(name))
+        info.appendChild(nameEl)
+    }
+
+    if (role) {
+        const roleEl = document.createElement('div')
+        roleEl.className = `${p}__role`
+        roleEl.appendChild(parseInline(role))
+        info.appendChild(roleEl)
+    }
+
+    if (bio) {
+        const bioEl = document.createElement('div')
+        bioEl.className = `${p}__bio`
+        bioEl.appendChild(parseInline(bio))
+        info.appendChild(bioEl)
+    }
+
+    const validLinks = (links || []).filter(/** @type {(l: import('../../types').PersonLink) => boolean} */ (l => !!l.url))
+    if (validLinks.length > 0) {
+        const linksEl = document.createElement('div')
+        linksEl.className = `${p}__links`
+        for (const link of validLinks) {
+            const a = document.createElement('a')
+            a.className = `${p}__link`
+            setSafeUrlAttribute(a, 'href', link.url, 'external')
+            a.target = '_blank'
+            a.rel = 'noopener noreferrer'
+            a.title = link.type || t('renderer.person.link', 'Link')
+
+            const iconSpan = document.createElement('span')
+            iconSpan.className = `${p}__link-icon`
+            iconSpan.innerHTML = (link.type && SOCIAL_ICONS[link.type]) || SOCIAL_ICONS.website
+            a.appendChild(iconSpan)
+
+            const urlSpan = document.createElement('span')
+            urlSpan.className = `${p}__link-url`
+            urlSpan.textContent = link.url.replace(/^https?:\/\//, '')
+            a.appendChild(urlSpan)
+
+            linksEl.appendChild(a)
+        }
+        info.appendChild(linksEl)
+    }
+
+    card.appendChild(info)
+    return card
+}

package/dist/renderer/renderers/person/locale/en.d.ts

@@ -0,0 +1,6 @@
+declare const _default: {
+    'renderer.person.link': string;
+    'renderer.person.previous': string;
+    'renderer.person.next': string;
+};
+export default _default;

package/dist/renderer/renderers/person/locale/en.js

@@ -0,0 +1,5 @@
+export default {
+  'renderer.person.link': 'Link',
+  'renderer.person.previous': 'Previous person',
+  'renderer.person.next': 'Next person',
+}

package/dist/renderer/renderers/person/locale/ru.d.ts

@@ -0,0 +1,6 @@
+declare const _default: {
+    'renderer.person.link': string;
+    'renderer.person.previous': string;
+    'renderer.person.next': string;
+};
+export default _default;

package/dist/renderer/renderers/person/locale/ru.js

@@ -0,0 +1,5 @@
+export default {
+  'renderer.person.link': 'Ссылка',
+  'renderer.person.previous': 'Предыдущая персона',
+  'renderer.person.next': 'Следующая персона',
+}

package/dist/renderer/renderers/person/styles.css

@@ -0,0 +1,47 @@
+.editor-person{padding:1rem 0}
+
+/* ── Multi-person list (default: flex row centered) ── */
+.editor-person__list{display:flex;gap:1rem;justify-content:center;flex-wrap:wrap}
+
+/* ── Carousel container ── */
+.editor-person__carousel .carousel__slide .editor-person__card{width:100%;padding:1.25rem;border:1px solid var(--er-border,#1e1e24);border-radius:8px;box-sizing:border-box}
+
+.editor-person__list .editor-person__card{flex-shrink:0;width:300px;padding:1.25rem;border:1px solid var(--er-border,#1e1e24);border-radius:8px}
+
+/* ── Nav buttons (below carousel) ── */
+.editor-person__nav{display:flex;justify-content:center;gap:0.5rem;margin-top:1rem}
+.editor-person__nav-btn{width:2rem;height:2rem;border-radius:50%;border:1px solid var(--er-border,#1e1e24);background:transparent;color:var(--er-text-3,#6e6e78);display:flex;align-items:center;justify-content:center;cursor:pointer;transition:border-color 0.15s,color 0.15s;outline:none}
+.editor-person__nav-btn:hover{border-color:var(--er-accent,#4357b4);color:var(--er-accent,#4357b4)}
+
+/* ── Card ── */
+.editor-person__card{display:flex;gap:1rem;align-items:flex-start}
+
+.editor-person__avatar-wrap{position:relative;flex-shrink:0;width:10rem;height:10rem;border-radius:50%;overflow:hidden}
+
+.editor-person__list .editor-person__avatar-wrap{width:5rem;height:5rem}
+
+.editor-person__avatar-img{width:100%;height:100%;object-fit:cover;display:block}
+
+.editor-person__info{flex:1;min-width:0;display:flex;flex-direction:column;gap:0.125rem}
+
+.editor-person__name{font-weight:600;font-size:1rem;color:var(--er-text-1);line-height:1.4}
+
+.editor-person__list .editor-person__name{font-size:0.9375rem}
+
+.editor-person__role{font-size:0.8125rem;color:var(--er-text-3);line-height:1.4}
+
+.editor-person__list .editor-person__role{font-size:0.75rem}
+
+.editor-person__bio{font-size:0.8125rem;color:var(--er-text-2);line-height:1.5;margin-top:0.25rem}
+
+.editor-person__list .editor-person__bio{font-size:0.75rem;display:-webkit-box;-webkit-line-clamp:3;-webkit-box-orient:vertical;overflow:hidden}
+
+.editor-person__links{margin-top:0.75rem;display:flex;flex-direction:column;gap:0.25rem}
+
+.editor-person__link{display:flex;align-items:center;gap:0.5rem;text-decoration:none;color:var(--er-text-3);font-size:0.75rem;line-height:1.75rem;transition:color 0.15s}
+
+.editor-person__link:hover{color:var(--er-text-1)}
+
+.editor-person__link-icon{display:flex;align-items:center;justify-content:center;flex-shrink:0;width:1.25rem;height:1.25rem;color:inherit}
+
+.editor-person__link-url{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}

package/dist/renderer/renderers/poll/README.md

@@ -0,0 +1,68 @@
+# Poll renderer
+
+Renderer for the `poll` block. It converts persisted block data into renderer-owned DOM.
+
+The `@shelamkoff/rector/renderer` entry contains the synchronous built-in preset, so `@shelamkoff/carousel` and `@shelamkoff/expose` must be installed before importing it. Passing `blockTypes: []` prevents default renderer construction but does not change ESM module resolution.
+
+## Usage
+
+```js
+import { createEditorRenderer } from '@shelamkoff/rector/renderer'
+import { createPollRenderer } from '@shelamkoff/rector/renderer/renderers/poll'
+
+const renderer = createEditorRenderer({ classPrefix: 'article', blockTypes: [] })
+renderer.registerRenderer(createPollRenderer('article', {}, {
+  dataSource: {
+    load: ({ pollId, signal }) => api.getPollResults(pollId, { signal }),
+    vote: ({ pollId, optionIds, revision, signal }) => (
+      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()
+    },
+  },
+  onError: error => console.error('Poll renderer data source failed', error),
+}))
+const rendererStyles = renderer.injectStyles()
+renderer.renderTo(documentData, document.querySelector('#article'))
+
+// When the mounted output is removed:
+renderer.destroy()
+rendererStyles.destroy()
+```
+
+## Typical 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 }] }
+}
+```
+
+The complete persisted and live-result contract is defined by the matching [Poll plugin](../../../plugins/poll/README.md#field-reference).
+
+## Configuration
+
+The third argument of `createPollRenderer(classPrefix, locale, config)` accepts the same runtime result source as the editor plugin:
+
+| Field | Meaning |
+| --- | --- |
+| `dataSource` | Optional server adapter. `load` and `vote` are required; `subscribe` is optional. Without it, voting updates renderer-local state initialized from `initialResults`. |
+| `onError` | Optional observer for load, vote, subscription, cleanup, or revision-comparator errors. The renderer still displays its localized error state. |
+| `maxVoters` | Maximum number of voter records retained from each result. Finite values are rounded down and clamped to zero; omitted or non-finite values use `50`. |
+| `compareRevisions` | Optional `(next, current) => number` comparator for opaque server revisions. Return a positive number only when `next` is newer. Without it, unequal revisions follow arrival order. |
+
+`dataSource` is used only when persisted data contains a non-empty `pollId`. `load` obtains the first authoritative snapshot. `vote` receives the complete current selection and the displayed revision and must return another authoritative snapshot. `subscribe` sends later snapshots through `onUpdate`; report connection errors through its `onError` callback and return an idempotent cleanup function. Every callback receives an `AbortSignal`; stop outstanding work when it is aborted. Every result must contain `total` (the ballot-count percentage denominator) and one `{ id, votes }` entry for every current option. Multiple-choice option counts may sum above `total`.
+
+Question and option text use the inline parser; voter avatars use the media URL policy. Live results are runtime state and do not change the document passed to `renderTo()`. The renderer owns vote state, cancellation, subscriptions, and controls and releases them in `destroy()`. It declares one stylesheet.
+
+When styles are declared, the explicit `EditorRenderer.injectStyles()` call shown above acquires them and its returned owner releases them.
+
+The VitePress guide documents renderer ownership, inline widget reconstruction, styles, cleanup, and security boundaries.

package/dist/renderer/renderers/poll/README.ru.md

@@ -0,0 +1,68 @@
+# Рендерер Poll
+
+Преобразует сохранённый блок `poll` в принадлежащий рендереру DOM.
+
+Синхронная точка входа `@shelamkoff/rector/renderer` включает все встроенные рендереры, поэтому до её импорта установите `@shelamkoff/carousel` и `@shelamkoff/expose`. Значение `blockTypes: []` отключает создание встроенных рендереров, но не меняет правила разрешения модулей ESM.
+
+## Использование
+
+```js
+import { createEditorRenderer } from '@shelamkoff/rector/renderer'
+import { createPollRenderer } from '@shelamkoff/rector/renderer/renderers/poll'
+
+const renderer = createEditorRenderer({ classPrefix: 'article', blockTypes: [] })
+renderer.registerRenderer(createPollRenderer('article', {}, {
+  dataSource: {
+    load: ({ pollId, signal }) => api.getPollResults(pollId, { signal }),
+    vote: ({ pollId, optionIds, revision, signal }) => (
+      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()
+    },
+  },
+  onError: error => console.error('Ошибка источника данных рендерера Poll', error),
+}))
+const rendererStyles = renderer.injectStyles()
+renderer.renderTo(documentData, document.querySelector('#article'))
+
+// При удалении добавленного результата:
+renderer.destroy()
+rendererStyles.destroy()
+```
+
+## Типичные данные
+
+```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 }] }
+}
+```
+
+Полный контракт сохранённых данных и текущих результатов описан в [справочнике полей плагина Poll](../../../plugins/poll/README.ru.md#поля-данных).
+
+## Конфигурация
+
+Третий аргумент `createPollRenderer(classPrefix, locale, config)` принимает тот же источник текущих результатов, что и плагин редактора:
+
+| Поле | Назначение |
+| --- | --- |
+| `dataSource` | Необязательный адаптер сервера. Методы `load` и `vote` обязательны, `subscribe` необязателен. Без адаптера голосование изменяет локальное состояние рендерера, начальное значение которого берётся из `initialResults`. |
+| `onError` | Необязательный обработчик ошибок загрузки, голосования, подписки, очистки или сравнения ревизий. Рендерер также показывает локализованное состояние ошибки. |
+| `maxVoters` | Наибольшее число записей о проголосовавших, сохраняемое из каждого результата. Конечное значение округляется вниз и ограничивается снизу нулём; при отсутствии или некорректном значении используется `50`. |
+| `compareRevisions` | Необязательная функция `(next, current) => number` для сравнения непрозрачных ревизий сервера. Возвращайте положительное число, только если `next` новее. Без функции разные ревизии применяются в порядке поступления. |
+
+`dataSource` используется, только если в сохранённых данных есть непустой `pollId`. `load` получает первый достоверный снимок. `vote` получает весь текущий выбор и отображаемую ревизию и должен вернуть новый достоверный снимок. `subscribe` передаёт последующие снимки через `onUpdate`; сообщайте об ошибках соединения через переданный `onError` и возвращайте функцию очистки, которую можно безопасно вызвать повторно. Каждый обратный вызов получает `AbortSignal`; прекращайте незавершённую работу после его прерывания. Каждый результат должен содержать `total` — число бюллетеней и знаменатель процентов — и по одному элементу `{ id, votes }` для каждого текущего варианта. При множественном выборе сумма голосов вариантов может превышать `total`.
+
+Вопрос и варианты проходят обработчик внутристрочной разметки, а аватары — политику URL для медиафайлов. Текущие результаты существуют только во время работы и не изменяют документ, переданный в `renderTo()`. Рендерер владеет состоянием голосования, отменой запросов, подписками и элементами управления и освобождает их в `destroy()`. Он объявляет одну таблицу стилей.
+
+Если рендерер объявляет стили, показанный выше явный вызов `EditorRenderer.injectStyles()` подключает их, а возвращённый владелец освобождает.
+
+Жизненный цикл, восстановление внутристрочных виджетов, стили и границы безопасности описаны в последовательном руководстве VitePress.

package/dist/renderer/renderers/poll/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Interactive poll renderer. Author configuration stays in the document;
+ * remote counts and voters are owned by the mounted renderer instance.
+ * @param {string} classPrefix
+ * @param {Record<string, any>} locale
+ * @param {import('../../types.js').PollRendererConfig} [config]
+ * @returns {import('../../types.js').BlockRenderer<import('../../types.js').PollBlock>}
+ */
+export function createPollRenderer(classPrefix: string, locale: Record<string, any>, config?: import("../../types.js").PollRendererConfig): import("../../types.js").BlockRenderer<import("../../types.js").PollBlock>;