@shelamkoff/rector 1.0.0

package/dist/plugins/link-preview/README.ru.md

@@ -0,0 +1,70 @@
+# Блочный плагин LinkPreview
+
+Предварительный просмотр ссылки с семью шаблонами и необязательными метаданными приложения.
+
+## Установка и регистрация
+
+```bash
+npm install @shelamkoff/rector
+```
+
+```js
+import { createEditor } from '@shelamkoff/rector'
+import { LinkPreview } from '@shelamkoff/rector/plugins/link-preview'
+import '@shelamkoff/rector/styles/editor.css'
+
+const editor = createEditor({
+  holder: document.querySelector('#editor'),
+  plugins: [new LinkPreview()],
+})
+```
+
+Тип блока — `linkPreview`. Класс также экспортируется общей точкой входа `@shelamkoff/rector/plugins` и может загружаться по типу документа через `@shelamkoff/rector/plugins/async`.
+
+## Данные
+
+```json
+{
+  "url": "https://example.com",
+  "title": "Пример",
+  "description": "",
+  "image": "",
+  "favicon": "",
+  "domain": "example.com",
+  "template": "notion"
+}
+```
+
+### Поля данных
+
+| Поле | Обязательное | Назначение и ограничения |
+| --- | --- | --- |
+| `url` | да | Канонический внешний адрес HTTP или HTTPS. |
+| `title`, `description`, `domain` | нет | Строки метаданных; пустые значения допустимы. |
+| `image`, `favicon` | нет | Пустые строки или канонические адреса, разрешённые политикой медиафайлов. |
+| `template` | нет | `horizontal`, `compact`, `large-top`, `minimal`, `twitter`, `notion` или `split`; редактор и рендерер по умолчанию используют `notion`. |
+
+`template` принимает `horizontal`, `compact`, `large-top`, `minimal`, `twitter`, `notion` или `split`. Разрешены только ссылки HTTP и HTTPS.
+
+## Конфигурация
+
+Каждый встроенный блочный плагин принимает два параметра владения стилями: `injectStyles?: boolean` по умолчанию равен `true`; укажите `false`, если приложение само включает CSS этого плагина. `css?: string` добавляет URL таблицы стилей приложения после стандартной, а при отключённой стандартной инъекции служит URL замены.
+
+`fetchMeta(url, { signal })` возвращает `title`, `description`, `image`, `favicon` и `domain` и должен учитывать переданный `AbortSignal`. Адреса изображения и значка проходят общую политику адресов медиафайлов. Без этого обработчика плагин не выполняет запрос метаданных: он сохраняет очищенный URL, определяет `domain`, а остальные поля остаются пустыми, пока их не передаст приложение или загруженный документ.
+
+Если настроен `fetchMeta`, ввод нового адреса запускает одно отменяемое получение метаданных. После завершения обработчика плагин одновременно сохраняет адрес и нормализованные метаданные, поэтому один ввод адреса остаётся одним шагом отмены и повтора. При ошибке сохраняется очищенный адрес без необязательных метаданных. Новый адрес или удаление блока прерывает предыдущий запрос и не позволяет устаревшему ответу изменить документ.
+
+
+## Возможности
+
+Вставка URL; асинхронное получение метаданных; выбор шаблона; безопасное назначение URL; освобождение ресурсов. Пока блок доступен для редактирования, нажатие карточки не открывает адрес и не уводит пользователя из редактора. В режиме отображения редактора и в готовом документе карточка работает как обычная внешняя ссылка.
+
+## История, жизненный цикл и стили
+
+Действия плагина входят в конвейер команд через предоставленный контекст `mutate()`, поэтому одно завершённое действие создаёт один шаг отмены и повтора. Редактор подсчитывает владельцев объявленных URL стилей. Удаление блока вызывает его метод освобождения ресурсов; `editor.destroy()` освобождает оставшиеся блоки и общие ресурсы.
+
+Не удаляйте контейнер редактора до вызова `editor.destroy()`.
+
+## Вывод документа
+
+Используйте фабричную функцию из `@shelamkoff/rector/renderer/renderers/link-preview`. Последовательное руководство VitePress описывает проверку данных, миграции, разработку расширений, диагностику, безопасность и стили.

package/dist/plugins/link-preview/index.d.ts

@@ -0,0 +1,169 @@
+import type {} from './locale/keys.js'
+/**
+ * Rich external-link card with optional metadata resolution and selectable
+ * presentation templates.
+ * @extends {BlockPluginAbstract<LinkPreviewConfig>}
+ */
+export class LinkPreview extends BlockPluginAbstract<LinkPreviewConfig> {
+    static isTextBlock: boolean;
+    static styles: string[];
+    /**
+     * Create a LinkPreview instance with the supplied consumer configuration.
+     * @param {LinkPreviewConfig} [config]
+     */
+    constructor(config?: LinkPreviewConfig);
+    type: string;
+    icon: string;
+    inlineTools: boolean;
+    pasteConfig: {
+        patterns: RegExp[];
+    };
+    /**
+     * Return the localized toolbox label for this block.
+     * @returns {string} Localized toolbox title.
+     */
+    get title(): string;
+    /** Create an empty, serializable link-preview value. @returns {LinkPreviewState['data']} */
+    _defaultData(): LinkPreviewState["data"];
+    /**
+     * 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 {LinkPreviewState['data']}
+     */
+    save(element: HTMLElement): LinkPreviewState["data"];
+    /**
+     * Check whether serialized data satisfies this block's schema.
+     * @param {Record<string, unknown>} d @returns {boolean}
+     */
+    validate(d: 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;
+    };
+    /**
+     * Handle supported pasted content for this block.
+     * @param {import('../../types.js').PasteEvent} event
+     * @returns {LinkPreviewState['data'] | null}
+     */
+    onPaste(event: import("../../types.js").PasteEvent): LinkPreviewState["data"] | null;
+    /**
+     * Release listeners and resources owned by this block element.
+     * @param {HTMLElement} element @returns {void}
+     */
+    destroy(element: HTMLElement): void;
+    /** @param {HTMLElement} wrapper @returns {void} */
+    _renderUrlBar(wrapper: HTMLElement): void;
+    /**
+     * @param {HTMLElement} wrapper
+     * @param {string} url
+     * @returns {void}
+     */
+    _processUrl(wrapper: HTMLElement, url: string): void;
+    /**
+     * Refresh the card after the current URL has finished resolving.
+     * @param {HTMLElement} wrapper
+     * @param {string} url
+     * @returns {void}
+     */
+    _renderResolvedUrl(wrapper: HTMLElement, url: string): void;
+    /**
+     * @param {HTMLElement} wrapper
+     * @param {string} url
+     * Resolve and normalize metadata without changing serialized block data.
+     * A `null` result means the request was superseded or the block was removed.
+     * Network and application errors still resolve to an empty object so the
+     * sanitized URL can be committed as one complete user action.
+     * @returns {Promise<LinkPreviewMeta | null>}
+     */
+    _resolveMeta(wrapper: HTMLElement, url: string): Promise<LinkPreviewMeta | null>;
+    /**
+     * Apply already-normalized metadata to the current state.
+     * @param {LinkPreviewState} state
+     * @param {LinkPreviewMeta} meta
+     * @returns {void}
+     */
+    _applyMeta(state: LinkPreviewState, meta: LinkPreviewMeta): void;
+    /** @param {HTMLElement} wrapper @returns {void} */
+    _removeCardElements(wrapper: HTMLElement): void;
+    /** @param {HTMLElement} wrapper @returns {void} */
+    _renderCard(wrapper: HTMLElement): void;
+    /** @param {HTMLElement} wrapper @returns {void} */
+    _renderActions(wrapper: HTMLElement): void;
+    /**
+     * @param {HTMLElement} wrapper
+     * @param {AbortSignal} [signal]
+     * @returns {HTMLElement}
+     */
+    _buildTemplatePanel(wrapper: HTMLElement, signal?: AbortSignal): HTMLElement;
+}
+export type LinkPreviewMeta = {
+    /**
+     * Human-readable page title.
+     */
+    title?: string;
+    /**
+     * Plain-text page summary.
+     */
+    description?: string;
+    /**
+     * Absolute or media-safe preview image URL.
+     */
+    image?: string;
+    /**
+     * Absolute or media-safe site icon URL.
+     */
+    favicon?: string;
+    /**
+     * Display domain; the plugin derives it from the URL when omitted.
+     */
+    domain?: string;
+};
+export type LinkPreviewConfig = {
+    /**
+     * Resolves metadata for a sanitized external HTTP(S) URL. Without it the card uses URL-derived fields only and performs no metadata request.
+     */
+    fetchMeta?: (url: string, context: {
+        signal: AbortSignal;
+    }) => Promise<LinkPreviewMeta>;
+    /**
+     * Whether the editor should load the built-in link-preview stylesheet.
+     */
+    injectStyles?: boolean;
+    /**
+     * Additional stylesheet URL, or the replacement URL when `injectStyles` is `false`.
+     */
+    css?: string;
+};
+export type LinkPreviewState = {
+    data: {
+        url: string;
+        title: string;
+        description: string;
+        image: string;
+        favicon: string;
+        domain: string;
+        template: string;
+    };
+    wrapper: HTMLDivElement;
+    lifecycleController: AbortController;
+    requestController: AbortController | null;
+    pendingUrl: string | null;
+    urlIconEl: HTMLElement | null;
+    inputTimer: ReturnType<typeof setTimeout> | null;
+    context: import("../../core/types.js").BlockMutationContext;
+};
+import { BlockPluginAbstract } from '../BlockPluginAbstract.js';