@olddevs/ui 0.0.0-stage → 4.0.1

package/dist/editor/core/schema.d.ts

@@ -0,0 +1,479 @@
+import type { CustomAttribute, PrefixedName, ToolEntry } from "./customTool.js";
+/**
+ * Схема Редактора ДАННЫМИ: белый список тегов и атрибутов, которые он
+ * принимает и отдаёт.
+ *
+ * ЗАЧЕМ ОТДЕЛЬНЫМ СПИСКОМ, ЕСЛИ СХЕМУ И ТАК ЗАДАЮТ РАСШИРЕНИЯ. Расширения
+ * Tiptap описывают схему кодом, и прочитать из них «что может прийти в HTML»
+ * нельзя ни человеку, ни санитайзеру. А потребителю нужен ровно этот ответ:
+ * санитизация на сервере — его ответственность (ADR-0050), и очистку
+ * (`sanitizeRichText` ниже) кит строит отсюда, а не из исходника. Совпадение списка с
+ * тем, что редактор реально отдаёт, сторожит
+ * `tests/rich-text-editor-schema.test.tsx` — в обе стороны.
+ *
+ * Список растёт вместе с набором Блоков и Меток;
+ * опубликован он на странице `RichTextView`, и таблица там сверяется с этим
+ * файлом тестом (`tests/rich-text-view.test.tsx`). Атрибута `style` в нём нет,
+ * кроме одного узкого исключения — произвольного цвета (`customColor` ниже):
+ * цвет палитры и выравнивание пишутся в `data-*` (спека, «Схема и
+ * безопасность»).
+ *
+ * Модуль серверно-безопасен: данные, без React и без движка. Его импорты —
+ * `palette.ts`, `customColor.ts`, `codeLanguages.ts`, `columnLayouts.ts` и
+ * `wrapperTones.ts`, тоже данные: имена палитры, языков, вариантов Раскладки и
+ * тонов Обёртки живут там один раз; ещё `lib/dev-warn.ts` — предупреждение
+ * разработчику без зависимостей.
+ */
+export declare const RICH_TEXT_SCHEMA: {
+    /**
+     * Блоки. `h1` — только с инструментом `heading1`: экран, у
+     * которого заголовок страницы стоит над Редактором, его выключает, и тогда
+     * Редактор `h1` не отдаёт. Схема-данные перечисляют всё, что кит МОЖЕТ
+     * отдать, а не то, что отдаёт при конкретном наборе `tools`.
+     * `pre` — блок кода, внутри него `code`. `figure` — картинка: внутри неё
+     * `img` и, если подпись не пуста, `figcaption`. Вне `figure` Редактор не
+     * отдаёт ни `img`, ни `figcaption`.
+     *
+     * `label`, `input`, `span` и `div` — разметка пункта чек-листа, как её пишет
+     * Tiptap: `<li data-type="taskItem"><label><input type="checkbox"><span>
+     * </span></label><div>…</div></li>`. Вне пункта чек-листа Редактор их не
+     * отдаёт, и `sanitizeRichText` держит их там же — хуком на предка.
+     *
+     * `div` с `data-block` — Раскладка: `div[data-block="layout"]`
+     * с вариантом в `data-layout`, внутри от одной до четырёх
+     * `div[data-block="column"]`, в колонке — Блоки, кроме другой Раскладки.
+     * Раскладка — только Блок верхнего уровня: не в колонке, Обёртке, списке,
+     * цитате и ячейке. Ширины колонок — вариантом, а не `style` (`layouts` ниже).
+     *
+     * `div[data-block="wrapper"]` — Обёртка, группа Блоков, как у
+     * Redactor; тон, если есть, — в `data-tone` (`wrapperTones` ниже).
+     * Стоит на верхнем уровне и прямо в колонке Раскладки; внутри — Блоки, кроме
+     * другой Обёртки и Раскладки.
+     *
+     * Таблица — `table > tbody > tr > th|td`, без `thead`, `colgroup` и
+     * `caption`: строка-заголовок — это обычная первая строка из `th`. На ячейке
+     * бывают только слияние (`colspan`, `rowspan`) и выравнивание столбца
+     * (`data-align`); ширина столбцов не строится, и `style` и `colwidth` на
+     * выходе не бывают. `tbody`, `tr`, `th` и `td` вне таблицы парсер HTML
+     * выбрасывает сам, хук на это не нужен.
+     */
+    readonly blocks: readonly ["p", "h1", "h2", "h3", "h4", "ul", "ol", "li", "blockquote", "hr", "pre", "table", "tbody", "tr", "th", "td", "label", "input", "span", "div", "figure", "img", "figcaption"];
+    /**
+     * Метки и строчные узлы. `br` — мягкий перенос по Shift+Enter. `mark` —
+     * маркер, всегда с `data-color`; `span` с `data-color` — цвет текста (тег
+     * назван в `blocks`: там он же — разметка пункта чек-листа). `a` — ссылка,
+     * её адрес ограничен схемами из `protocols`.
+     */
+    readonly marks: readonly ["strong", "em", "u", "s", "code", "sup", "sub", "mark", "br", "a"];
+    /** Атрибуты по тегам. Всё, чего здесь нет, на выходе не появляется. */
+    readonly attributes: {
+        /** Номер первого пункта — только когда он не 1. */
+        readonly ol: readonly ["start"];
+        /** Чек-лист: `data-type="taskList"`. */
+        readonly ul: readonly ["data-type"];
+        /**
+         * Раскладка и её колонка: `data-block="layout"` и `data-block="column"`;
+         * `data-layout` — вариант из `layouts`, только у Раскладки. Обёртка —
+         * `data-block="wrapper"` и, если у неё есть тон, `data-tone` — имя из
+         * `wrapperTones`, только у Обёртки. У `div` пункта чек-листа атрибутов нет.
+         */
+        readonly div: readonly ["data-block", "data-layout", "data-tone"];
+        /** Пункт чек-листа: `data-type="taskItem"` и `data-checked="true|false"`. */
+        readonly li: readonly ["data-type", "data-checked"];
+        /** Флажок пункта чек-листа: всегда `type="checkbox"`, `checked` — у отмеченного. */
+        readonly input: readonly ["type", "checked"];
+        /**
+         * Язык блока кода: только `language-<имя>` с именем из `codeLanguages` и
+         * только на `code` внутри `pre`. Подсветка в Документ не пишется — токены
+         * `hljs-*` живут декорациями Редактора (ADR-0051). Другие классы Редактор
+         * не отдаёт, блок без языка — `<code>` без класса.
+         */
+        readonly code: readonly ["class"];
+        /**
+         * Цвет текста и маркер: имя в `data-color` ИЛИ произвольный цвет в `style`
+         * (`customColor`) — вместе на одном элементе не бывают. Палитры две:
+         * `span[data-color]` — имя из `textColors`, `mark[data-color]` — имя из
+         * `markerColors`; имя чужой палитры на теге не принимается. Другое имя
+         * Редактор не отдаёт и при загрузке отбрасывает вместе с обёрткой (старые
+         * имена маркера он переводит — `legacyMarkerColors`). На `span` без
+         * `data-color` и без `style` он тоже не бывает — пустой `span` есть только
+         * в пункте чек-листа.
+         */
+        readonly span: readonly ["data-color", "style"];
+        readonly mark: readonly ["data-color", "style"];
+        /**
+         * Выравнивание Блока: значение из `alignments`, кроме `left` — оно
+         * умолчание, и Редактор его не пишет (читает как отсутствие атрибута).
+         */
+        readonly p: readonly ["data-align"];
+        /**
+         * Ячейка таблицы: слияние — `colspan` и `rowspan`, целое больше 1 и не
+         * больше `tableSpans` (1 Редактор не пишет — это умолчание); выравнивание
+         * столбца — `data-align` со значением из `alignments`, кроме `left`, на
+         * каждой ячейке столбца.
+         */
+        readonly th: readonly ["colspan", "rowspan", "data-align"];
+        readonly td: readonly ["colspan", "rowspan", "data-align"];
+        readonly h1: readonly ["data-align"];
+        readonly h2: readonly ["data-align"];
+        readonly h3: readonly ["data-align"];
+        readonly h4: readonly ["data-align"];
+        /**
+         * Ссылка: `href` только со схемой из `protocols`, `rel` всегда
+         * `"noopener noreferrer"`. `target` Редактор не отдаёт: новая вкладка —
+         * решение страницы показа, а не данных Документа.
+         */
+        readonly a: readonly ["href", "rel"];
+        /**
+         * Картинка: `src` только абсолютный `http` или `https` (`imageProtocols`),
+         * `alt` есть всегда — пустой у картинки без описания, — `data-width` —
+         * значение из `imageWidths`, только у картинки с заданной шириной.
+         */
+        readonly img: readonly ["src", "alt", "data-width"];
+    };
+    /**
+     * Допустимые значения `span[data-color]` — цвет текста: шесть тонов статуса.
+     * Значение вне списка `sanitizeRichText` снимает вместе с атрибутом:
+     * `ALLOWED_ATTR` у DOMPurify значений не проверяет, и проверять надо по
+     * тегу — имя маркера на `span` не годится.
+     */
+    readonly textColors: readonly ("accent" | "success" | "warning" | "danger" | "lime" | "muted")[];
+    /**
+     * Допустимые значения `mark[data-color]` — маркер: девять названий цвета.
+     * Те же правила, что у `textColors`, и свой тег.
+     */
+    readonly markerColors: readonly ("blue" | "green" | "red" | "pink" | "brown" | "gray" | "orange" | "purple" | "yellow")[];
+    /**
+     * Старые имена `mark[data-color]` — шесть имён цвета текста, которыми маркер
+     * назывался до палитры Notion, — и цвет, в который их переводит Редактор при
+     * загрузке и вставке. `sanitizeRichText` делает то же ДО проверки по
+     * `markerColors`: иначе подсветка у сохранённого документа пропадёт. На
+     * `span` перевода нет.
+     */
+    readonly legacyMarkerColors: {
+        readonly accent: "blue";
+        readonly success: "green";
+        readonly warning: "yellow";
+        readonly danger: "red";
+        readonly lime: "green";
+        readonly muted: "gray";
+    };
+    /**
+     * ЕДИНСТВЕННОЕ место, где в документе бывает `style` — произвольный цвет,
+     * выбранный автором в `ColorPicker`. Исключение узкое и принято
+     * владельцем: у цвета автора нет имени, а носитель значения в HTML — `style`.
+     *
+     * `styles` — регулярное выражение (строкой) на ВСЁ значение атрибута по
+     * тегу: `span` — только `color:#rrggbb`, `mark` — только
+     * `background-color:#rrggbb`; строчные буквы, шесть цифр, без пробелов и
+     * `;`, ничего больше. Любой другой `style` Редактор при загрузке и вставке
+     * отбрасывает, а `sanitizeRichText` снимает — `ALLOWED_ATTR` у DOMPurify
+     * значений не проверяет, поэтому в голом `richTextSanitizeConfig()` `style`
+     * нет вовсе. `style` не бывает вместе с `data-color` на одном элементе.
+     *
+     * Цвет автора НЕ следует за темой — в отличие от `textColors` и `markerColors`: `#ff0000` одинаков
+     * в `dark`, `light` и `dim`, и контраст на какой-то из тем может не держать.
+     */
+    readonly customColor: {
+        readonly styles: {
+            readonly span: "^color:#[0-9a-f]{6}$";
+            readonly mark: "^background-color:#[0-9a-f]{6}$";
+        };
+    };
+    /**
+     * Языки блока кода — имена после `language-` в `class` у `<pre><code>`.
+     * Псевдонимы (`py`, `yml`) Редактор при загрузке приводит к
+     * имени, неизвестный язык — к блоку без класса; `sanitizeRichText` снимает
+     * `class` со значением вне этого списка, псевдонимы тоже.
+     */
+    readonly codeLanguages: readonly ("html" | "go" | "python" | "typescript" | "javascript" | "json" | "yaml" | "markdown")[];
+    /** Допустимые значения `data-align`; `left` читается, но не пишется. */
+    readonly alignments: readonly ["left", "center", "right"];
+    /**
+     * Варианты Раскладки — значения `div[data-layout]`: доли колонок в процентах
+     * через дефис (`50-50`, `60-40`, `25-25-25-25`). Число колонок Раскладки
+     * Редактор приводит к варианту при загрузке; сервер его не пересчитывает —
+     * лишняя или недостающая колонка в показе ничего не ломает.
+     */
+    readonly layouts: readonly ["100", "50-50", "33-33-33", "25-25-25-25", "60-40", "40-60"];
+    /**
+     * Тоны Обёртки — значения `div[data-tone]`: имена словаря `Tone`
+     * кита. Без тона атрибута нет; имя вне списка Редактор при загрузке
+     * отбрасывает (Обёртка остаётся), `sanitizeRichText` снимает атрибут. Цвет
+     * подставляет тема, как у `data-color`: в HTML нет ни `style`, ни роли.
+     */
+    readonly wrapperTones: readonly ["accent", "success", "neutral", "warning", "danger"];
+    /**
+     * Схемы адреса ссылки. Только абсолютные адреса: `javascript:`, `data:` и
+     * прочие схемы не проходят ни из `value`, ни из вставки, ни из поповера.
+     *
+     * ПОЧЕМУ БЕЗ ОТНОСИТЕЛЬНЫХ (`/docs`, `#part`, `page.html`). Документ — данные,
+     * которые уезжают с экрана, где их написали: в `RichTextView` на другом
+     * маршруте, в письмо, в Markdown, в соседний продукт на другом домене.
+     * Относительный адрес там значит другое или ничего, а якорям в Документе не
+     * на что указывать — у заголовков нет `id`. Заодно адрес без схемы в поповере
+     * однозначен: `example.com` — это `https://example.com`, а не путь от
+     * текущей страницы. Ослабить правило потом можно без ломки сохранённого,
+     * ужесточить — уже нет.
+     */
+    readonly protocols: readonly ["http", "https", "mailto"];
+    /**
+     * Схемы адреса картинки — строже, чем у ссылки: `mailto:` картинкой не
+     * бывает, а `data:` и `blob:` не пишутся никогда (спека, «Схема и
+     * безопасность»). `data:` — это base64 внутри Документа: мегабайты в базе
+     * потребителя и в каждом `onChange`; `blob:` — адрес, живущий только в
+     * вкладке, где его создали, — после сохранения он ведёт в никуда.
+     */
+    readonly imageProtocols: readonly ["http", "https"];
+    /**
+     * Ширина картинки — доля ширины Документа в процентах: `data-width="50"`.
+     * Без атрибута картинка показывается в своём размере, но не шире Документа.
+     * Пресеты, а не любое число: ручки мышью прилипают к ним, и тот же набор
+     * доступен с клавиатуры в поповере картинки.
+     */
+    readonly imageWidths: readonly ["50", "75", "100"];
+    /**
+     * Предел слияния ячейки: `colspan` не больше 20, `rowspan` не больше 50 —
+     * столько же, сколько столбцов и строк у самой большой таблицы, которую
+     * Редактор вставляет. Значение сверх предела, ноль, дробь и не-число
+     * Редактор при загрузке и вставке читает как 1 (ячейка остаётся, слияние
+     * распадается), а санитайзеру стоит снимать атрибут: `colspan="10000"` —
+     * это десять тысяч пустых ячеек в каждом, кто таблицу откроет.
+     */
+    readonly tableSpans: {
+        readonly colspan: 20;
+        readonly rowspan: 50;
+    };
+};
+/**
+ * Правила Схемы своего Блока — данные из описания своего Инструмента
+ * (`CustomBlock`) с заполненными умолчаниями. Признаков Блока здесь нет: это
+ * поведение Редактора, а не то, что может прийти в HTML.
+ */
+export interface RichTextCustomBlockRules {
+    /** Блочный — `div[data-block="<имя>"]`, строчный — `span[data-block="<имя>"]`. */
+    kind: "block" | "inline";
+    /** `top` — только верхний уровень Документа (бывает только у блочного). */
+    place: "anywhere" | "top";
+    /** Свои атрибуты: имя без `data-` — вид значения. */
+    attributes: Readonly<Record<PrefixedName, CustomAttribute>>;
+}
+/** Правила Схемы своей Метки — `span[data-mark="<имя>"]` и её атрибуты. */
+export interface RichTextCustomMarkRules {
+    attributes: Readonly<Record<PrefixedName, CustomAttribute>>;
+}
+/** Схема данными с правилами своих Инструментов — результат `richTextSchema(tools)`. */
+export type RichTextSchema = typeof RICH_TEXT_SCHEMA & {
+    /** Свои Блоки и строчные атомы — по имени Блока. */
+    customBlocks: Readonly<Record<PrefixedName, RichTextCustomBlockRules>>;
+    /** Свои Метки — по имени Метки. */
+    customMarks: Readonly<Record<PrefixedName, RichTextCustomMarkRules>>;
+};
+/**
+ * Имя своего Блока, Метки и Инструмента: Префикс потребителя (буква, буквы и
+ * цифры), подчёркивание, остаток-слово — `acme_mergeTag`. В именах кита
+ * подчёркивания не бывает, поэтому своё и встроенное не пересекаются.
+ *
+ * @internal Им же проверяет набор Редактор (`customToolEngine.ts`).
+ */
+export declare const CUSTOM_NAME: RegExp;
+/**
+ * Имя своего атрибута — то же, но строчными: в HTML имена атрибутов без регистра.
+ *
+ * @internal
+ */
+export declare const CUSTOM_ATTRIBUTE_NAME: RegExp;
+/**
+ * HTML-соглашение своего правила (ADR-0058, п. 2): блочный Блок — `div`,
+ * строчный Блок и Метка — `span`; Блок помечен `data-block`, Метка —
+ * `data-mark`, значение — имя. Одно место на Редактор (`customToolEngine.ts`:
+ * разбор, вывод, сверка `renderHTML`) и очистку на сервере.
+ *
+ * @internal
+ */
+export declare function customElement(kind: "block" | "inline" | "mark"): {
+    tag: "div" | "span";
+    marker: "data-block" | "data-mark";
+};
+/**
+ * Схема Редактора данными для набора `tools` — тот же массив, что получает
+ * Редактор (ADR-0058, п. 2.3): Схема кита плюс правила своих Блоков и Меток.
+ *
+ * ИМЕНА КИТА БЕЛЫЙ СПИСОК НЕ СУЖАЮТ. Схема кита — по-прежнему всё, что кит
+ * может отдать, при любом наборе: экраны с `basic` и `full` пишут один
+ * Документ, и сервер одного не вправе срезать то, что записал другой. Описания
+ * своих Инструментов только добавляют правила. Без аргумента — Схема кита без
+ * своих правил; сама константа `RICH_TEXT_SCHEMA` не меняется.
+ *
+ * Правила с именем без Префикса потребителя здесь не читаются: Редактор такой
+ * набор отвергает ошибкой поля, а у сервера ошибок нет — и описание с именем
+ * кита (`wrapper`, атрибут `tone`) не должно открыть обход правил кита.
+ *
+ * Читаются только данные описания (`blocks`, `marks`), Часть для движка не
+ * трогается: модуль с описанием своего Инструмента импортируется на сервере,
+ * и Tiptap здесь не нужен.
+ */
+export declare function richTextSchema(tools?: readonly ToolEntry[]): RichTextSchema;
+/**
+ * Конфиг очистки для DOMPurify — ЗАКРЫТЫЙ ПО УМОЛЧАНИЮ. Безопасный путь —
+ * `sanitizeRichText(html, DOMPurify)` ниже: он ставит хуки Схемы и пропускает
+ * разметку Редактора целиком. Этот конфиг — для того, кто передаёт его
+ * DOMPurify напрямую: без хуков он не пропустит ничего опасного, но и часть
+ * разметки Редактора потеряется (цвет автора, язык блока кода, слияние ячеек,
+ * флажки чек-листа и картинки — `HOOK_GUARDED_ATTRIBUTES`).
+ *
+ * ПОЧЕМУ ФУНКЦИЯ НА МАССИВАХ, А НЕ ЗАВИСИМОСТЬ. DOMPurify кит не ставит и не
+ * импортирует: очистка — дело сервера потребителя (ADR-0050), а у него свой
+ * выбор — DOMPurify с jsdom, `isomorphic-dompurify`, другой санитайзер. Здесь
+ * только данные Схемы в форме, которую DOMPurify принимает, поэтому тип результата
+ * свой, а не его `Config`: структурно он ему присваивается.
+ *
+ * ПОЧЕМУ КАЖДЫЙ РАЗ НОВЫЕ МАССИВЫ. DOMPurify и вызывающий код вольны менять
+ * конфиг (`ALLOWED_ATTR.push("data-color")`), и общий массив протёк бы такой
+ * правкой в соседние вызовы.
+ *
+ * Что остаётся в общем `ALLOWED_ATTR` — безвредно на любом теге и с любым
+ * значением: имена `data-*` Схемы (их читает только типографика, и только свои
+ * значения), `start`, `alt`, `rel` и `href` — адрес сверяет выражение ниже.
+ * `ALLOW_DATA_ATTR` и `ALLOW_ARIA_ATTR` выключены: по умолчанию DOMPurify
+ * пропускает любые `data-*` и `aria-*`, а Схема знает свои `data-*` —
+ * `data-type`, `data-checked`, `data-color`, `data-align` и `data-width`, они
+ * названы в `ALLOWED_ATTR` поимённо и попадают туда из `attributes`.
+ *
+ * АДРЕС ССЫЛКИ — `ALLOWED_URI_REGEXP` по `protocols`, той же политикой, что в
+ * Редакторе: `javascript:`, `data:`, `ftp:` и относительные адреса `href` не
+ * проходят. DOMPurify сверяет с этим выражением не только `href`, а КАЖДЫЙ
+ * разрешённый атрибут, кроме «безопасных для URI», — и строгое выражение
+ * срезало бы `start="3"` и `data-type="taskList"`. Поэтому все атрибуты Схемы,
+ * кроме адресов (`href` и `src`), объявлены безопасными (`ADD_URI_SAFE_ATTR`)
+ * и сверяются только со списком имён. Атрибут, который добавит следующий
+ * срез, попадёт туда сам.
+ *
+ * Модуль серверно-безопасен: функция над данными, без React и без движка.
+ */
+export declare function richTextSanitizeConfig(): RichTextSanitizeConfig;
+/** Форма, которую принимает `DOMPurify.sanitize`; подмножество его `Config`. */
+export interface RichTextSanitizeConfig {
+    ALLOWED_TAGS: string[];
+    ALLOWED_ATTR: string[];
+    ALLOW_DATA_ATTR: false;
+    ALLOW_ARIA_ATTR: false;
+    /** Схемы адреса ссылки — `RICH_TEXT_SCHEMA.protocols`. */
+    ALLOWED_URI_REGEXP: RegExp;
+    /** Атрибуты, которые DOMPurify не сверяет с `ALLOWED_URI_REGEXP`: все, кроме `href` и `src`. */
+    ADD_URI_SAFE_ATTR: string[];
+}
+/** Событие хука `uponSanitizeAttribute`: подмножество того, что передаёт DOMPurify. */
+export interface RichTextAttributeHookEvent {
+    attrName: string;
+    attrValue: string;
+    keepAttr: boolean;
+}
+/**
+ * Экземпляр DOMPurify — ровно то, чем пользуется `sanitizeRichText`.
+ *
+ * ПОЧЕМУ СТРУКТУРНЫЙ ТИП, А НЕ ИМПОРТ ИЗ `dompurify`. Пакета в зависимостях кита
+ * нет и не будет (ADR-0050): потребитель приносит свой — `dompurify` с jsdom
+ * или `isomorphic-dompurify`. Экземпляр любого из них присваивается этому типу
+ * без приведений; это сторожит `tests/editor-sanitize.test.tsx` на настоящем
+ * DOMPurify.
+ */
+export interface RichTextPurifier {
+    sanitize(dirty: string, config: RichTextSanitizeConfig): string;
+    addHook(entryPoint: "uponSanitizeAttribute", hook: (node: Element, event: RichTextAttributeHookEvent) => void): void;
+    addHook(entryPoint: "afterSanitizeAttributes", hook: (node: Element) => void): void;
+    removeHook(entryPoint: "uponSanitizeAttribute", hook?: (node: Element, event: RichTextAttributeHookEvent) => void): unknown;
+    removeHook(entryPoint: "afterSanitizeAttributes", hook?: (node: Element) => void): unknown;
+}
+/**
+ * Очистить HTML Документа по Схеме Редактора — безопасный путь по умолчанию
+ * (ADR-0050): `sanitizeRichText(html, DOMPurify)` на сервере потребителя.
+ *
+ * ПОЧЕМУ ХЕЛПЕР, А НЕ РЕЦЕПТ НА СТРАНИЦЕ. Политика по тегам — где `style`
+ * бывает и с каким значением, какой `class` у `code`, где живут `label` и
+ * `input` — жила только в хуках, которые потребитель копировал со страницы
+ * `RichTextView`. Конфиг при этом разрешал `style` и `class` на любом теге:
+ * забытый или устаревший при копировании хук молча пропускал любой CSS. Теперь
+ * хуки — код кита, они меняются вместе со Схемой, а без них конфиг закрыт.
+ *
+ * ХУКИ — НА ВРЕМЯ ОДНОГО ВЫЗОВА. DOMPurify держит хуки на экземпляре, а
+ * экземпляр у потребителя общий (комментарии, письма, свои правила).
+ * Поставленные навсегда, правила Схемы срабатывали бы в чужой очистке. Хелпер
+ * ставит их перед `sanitize` и снимает после — по ссылке на функцию, поэтому
+ * свои хуки потребителя остаются на месте. Снятие по ссылке — DOMPurify 3.2+;
+ * старый `removeHook` без функции снимает последний поставленный, то есть тоже
+ * наш. `sanitize` синхронный: чужой вызов между установкой и снятием не
+ * вклинится.
+ *
+ * Что проверяют хуки (всё, что Редактор пишет, проходит без изменений):
+ *
+ * - `label`, `input`, `span`, `div` — только разметка пункта чек-листа; `input`
+ *   — только `type="checkbox"`;
+ * - `ol[start]` — только на `ol`; `ul`/`li[data-type]`, `li[data-checked]` —
+ *   только значения чек-листа;
+ * - `code[class]` — только канонический `language-<имя>` из `codeLanguages`;
+ * - `span[data-color]` и `mark[data-color]` — только имена своей палитры, старые
+ *   имена маркера переводятся (`legacyMarkerColors`); `mark` без цвета
+ *   снимается;
+ * - `style` — только `color:#rrggbb` на `span` и `background-color:#rrggbb` на
+ *   `mark` и никогда вместе с `data-color`;
+ * - `data-align` — известное значение на `p`, `h1`–`h4`, `th`, `td`;
+ * - Раскладка — `div[data-block="layout"]` с вариантом из `layouts` и только
+ *   вне колонки, списка, цитаты и таблицы; `div[data-block="column"]` — только
+ *   прямо в ней. Иначе обёртка снимается, Блоки остаются подряд;
+ * - Обёртка — `div[data-block="wrapper"]` на верхнем уровне или прямо в
+ *   колонке Раскладки, не в другой Обёртке, списке, цитате и таблице; иначе
+ *   снимается так же, вместе с тоном; `data-tone` — имя из `wrapperTones` и
+ *   только на Обёртке;
+ * - `colspan`, `rowspan` — на `th`/`td`, целое от 1 до `tableSpans`;
+ * - ссылка — `href` по `protocols` (выражение конфига), `rel` всегда
+ *   `"noopener noreferrer"`, ссылка без адреса становится текстом;
+ * - картинка — `img` с абсолютным `http`/`https` прямо в `figure`, без `data:`
+ *   и `blob:`, `data-width` — пресет, `alt` есть всегда; `figcaption` — только
+ *   в `figure`.
+ *
+ * Токенов подсветки `hljs-*` в Схеме нет, и хелпер их снимает: подсветка —
+ * после очистки (`highlightCodeBlocks`, ADR-0051).
+ *
+ * СВОИ ИНСТРУМЕНТЫ — ТРЕТЬИМ АРГУМЕНТОМ (ADR-0058, п. 2.3): тот же массив
+ * `tools`, что у Редактора. Свой Блок проходит как `div[data-block="<имя>"]`
+ * (строчный — `span`), своя Метка — как `span[data-mark="<имя>"]`, их атрибуты
+ * `data-<имя>` — только на своём элементе и только со значением по виду из
+ * правил (список, шаблон, адрес по политике протоколов ссылки); значение с
+ * разметкой не проходит никогда. Чужие теги и атрибуты на своём элементе
+ * снимаются, Блок с местом `top` вне верхнего уровня теряет обёртку, как
+ * Раскладка. Имена Инструментов кита белый список не сужают (`richTextSchema`).
+ * Без третьего аргумента очистка та же, что была до своих Инструментов.
+ *
+ * Модуль серверно-безопасен: DOM даёт экземпляр DOMPurify, кит его не
+ * импортирует.
+ */
+export declare function sanitizeRichText(html: string, purify: RichTextPurifier, tools?: readonly ToolEntry[]): string;
+/**
+ * Годится ли адрес для ссылки Документа: абсолютный, со схемой из
+ * `RICH_TEXT_SCHEMA.protocols`. Им проверяют и Редактор (загрузка, вставка,
+ * поповер), и конфиг очистки — правило одно на обе стороны.
+ *
+ * @internal Не входит в публичные входы: потребителю хватает конфига.
+ */
+export declare function isAllowedLinkHref(href: string): boolean;
+/**
+ * Годится ли адрес для картинки Документа: абсолютный `http` или `https`
+ * (`RICH_TEXT_SCHEMA.imageProtocols`) с именем хоста. `https:photo.png` без
+ * `//` браузер разобрал бы относительно страницы — такой адрес не проходит.
+ *
+ * @internal Не входит в публичные входы: потребителю хватает `sanitizeRichText`.
+ */
+export declare function isAllowedImageSrc(src: string): boolean;
+/**
+ * Годится ли значение своего атрибута по его виду (`CustomAttribute`). Одна
+ * проверка на Редактор (`customToolEngine.ts`) и очистку на сервере.
+ *
+ * Значение с `<` не проходит никогда, какой бы ни был шаблон: HTML в атрибутах
+ * запрещён (ADR-0058, п. 2.5) — содержимое Блока живёт разметкой Документа в
+ * его детях, где его чистит та же Схема.
+ *
+ * @internal Наружу отдаётся через `customTool.ts`.
+ */
+export declare function isAllowedAttributeValue(rule: CustomAttribute, value: string): boolean;
+//# sourceMappingURL=schema.d.ts.map

package/dist/editor/core/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/editor/core/schema.ts"],"names":[],"mappings":"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"}