@olddevs/ui 4.5.0 → 4.6.0

package/docs/components/content/rich-text-view.md

@@ -92,17 +92,17 @@ export default async function ArticlePage({ id }: { id: string }) {
 
 <!-- allow-list -->
 
-| Что      | Разрешено                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Блоки    | `p`, `h1`, `h2`, `h3`, `h4`, `ul`, `ol`, `li`, `blockquote`, `hr`, `pre`, `table`, `tbody`, `tr`, `th`, `td`; `label`, `input`, `span` — только внутри пункта чек-листа; `div` — там же, а ещё Раскладка и её колонки (Раскладка — только на верхнем уровне, колонка — только прямо в ней) и Обёртка (на верхнем уровне и прямо в колонке, не в другой Обёртке); `figure` — картинка, внутри неё `img` и необязательная `figcaption` (вне `figure` их нет)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| Метки    | `strong`, `em`, `u`, `s`, `code`, `sup`, `sub`, `mark` (только с цветом), `br`, `a`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| Атрибуты | `ol[start]` — только когда нумерация не с 1; `ul[data-type]`, `li[data-type]`, `li[data-checked]` — чек-лист; `input[type]`, `input[checked]` — его флажок; `code[class]` — язык блока кода, только «language-python», «language-typescript», «language-javascript», «language-go», «language-html», «language-json», «language-yaml» или «language-markdown» (без языка класса нет); `span[data-color]`, `mark[data-color]` — цвет текста и маркер, только имена палитры этого тега: на `span` цвета текста, на `mark` маркера; `span[style]`, `mark[style]` — произвольный цвет автора, только «color:#rrggbb» и «background-color:#rrggbb», и не вместе с «data-color»; `p[data-align]`, `h1[data-align]`, `h2[data-align]`, `h3[data-align]`, `h4[data-align]` — выравнивание Блока, по центру или справа; `th[colspan]`, `td[colspan]` — слияние по горизонтали, целое от 2 до 20; `th[rowspan]`, `td[rowspan]` — по вертикали, от 2 до 50; `th[data-align]`, `td[data-align]` — выравнивание столбца, по центру или справа, на каждой его ячейке; `a[href]` — только «http», «https» или «mailto»; `a[rel]` — всегда «noopener noreferrer»; `img[src]` — только абсолютный «http» или «https», без «data:» и «blob:»; `img[alt]` — всегда, пустой у картинки без описания; `img[data-width]` — 50, 75 или 100; `div[data-block]` — Раскладка («layout»), её колонка («column») и Обёртка («wrapper»); `div[data-layout]` — вариант Раскладки, доли колонок в процентах: «100», «50-50», «33-33-33», «25-25-25-25», «60-40» или «40-60»; `div[data-tone]` — тон Обёртки, только на ней: «neutral», «accent», «success», «warning» или «danger» (без тона атрибута нет) |
+| Что      | Разрешено                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Блоки    | `p`, `h1`, `h2`, `h3`, `h4`, `ul`, `ol`, `li`, `blockquote`, `hr`, `pre`, `table`, `tbody`, `tr`, `th`, `td`; `label`, `input`, `span` — только внутри пункта чек-листа; `div` — там же, а ещё Раскладка и её колонки (Раскладка — только на верхнем уровне, колонка — только прямо в ней) и Обёртка (на верхнем уровне и прямо в колонке, не в другой Обёртке); `details` — сворачиваемый Блок, внутри него `summary` и `div` содержимого (оба — только прямо в `details`; вне него теги снимаются); `figure` — картинка, внутри неё `img` и необязательная `figcaption` (вне `figure` их нет)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Метки    | `strong`, `em`, `u`, `s`, `code`, `sup`, `sub`, `mark` (только с цветом), `br`, `a`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Атрибуты | `ol[start]` — только когда нумерация не с 1; `ul[data-type]`, `li[data-type]`, `li[data-checked]` — чек-лист; `input[type]`, `input[checked]` — его флажок; `code[class]` — язык блока кода, только «language-python», «language-typescript», «language-javascript», «language-go», «language-html», «language-json», «language-yaml» или «language-markdown» (без языка класса нет); `span[data-color]`, `mark[data-color]` — цвет текста и маркер, только имена палитры этого тега: на `span` цвета текста, на `mark` маркера; `span[style]`, `mark[style]` — произвольный цвет автора, только «color:#rrggbb» и «background-color:#rrggbb», и не вместе с «data-color»; `p[data-align]`, `h1[data-align]`, `h2[data-align]`, `h3[data-align]`, `h4[data-align]` — выравнивание Блока, по центру или справа; `th[colspan]`, `td[colspan]` — слияние по горизонтали, целое от 2 до 20; `th[rowspan]`, `td[rowspan]` — по вертикали, от 2 до 50; `th[data-align]`, `td[data-align]` — выравнивание столбца, по центру или справа, на каждой его ячейке; `a[href]` — только «http», «https» или «mailto»; `a[rel]` — всегда «noopener noreferrer»; `img[src]` — только абсолютный «http» или «https», без «data:» и «blob:»; `img[alt]` — всегда, пустой у картинки без описания; `img[data-width]` — 50, 75 или 100; `div[data-block]` — Раскладка («layout»), её колонка («column») и Обёртка («wrapper»); `div[data-layout]` — вариант Раскладки, доли колонок в процентах: «100», «50-50», «33-33-33», «25-25-25-25», «60-40» или «40-60»; `div[data-tone]` — тон Обёртки, только на ней: «neutral», «accent», «success», «warning» или «danger» (без тона атрибута нет); `div[data-type]` — обёртка содержимого сворачиваемого Блока, только значение «detailsContent» и только прямо в `details`; `details[open]` — открытый Блок, только пустой «open» |
 
 Пункт чек-листа Tiptap пишет так: `<li data-type="taskItem" data-checked="true"><label><input type="checkbox" checked><span></span></label><div><p>…</p></div></li>`. `sanitizeRichText` пускает `input`, `label`, `span` и `div` только внутри такого пункта, а `input` — только с `type="checkbox"`.
 
 Таблицу Редактор пишет так: `<table><tbody><tr><th><p>…</p></th></tr><tr><td colspan="2" data-align="center"><p>…</p></td></tr></tbody></table>`. Строка-заголовок — первая строка из `th`, а у ячейки бывают только три атрибута: `colspan` и `rowspan` (слияние, целое от 2 до `RICH_TEXT_SCHEMA.tableSpans`: 20 по горизонтали и 50 по вертикали; 1 не пишется) и `data-align` (выравнивание столбца, `center` или `right`, на каждой ячейке столбца). Строка, целиком накрытая слиянием сверху, остаётся пустой `<tr></tr>`. `thead`, `tfoot`, `colgroup`, `caption` в Схеме нет, и **DOMPurify по умолчанию вместе с `thead` и `colgroup` убирает и их содержимое**: заголовок таблицы, пришедшей не из Редактора, записанный в `thead`, пропадёт. Редактор `thead` не пишет, так что для его HTML это не потеря. `tbody`, `tr`, `th` и `td` вне таблицы парсер HTML выбрасывает до очистки (текст остаётся), `style` и `colwidth` не проходят, а `colspan` и `rowspan` пропускает только хук `sanitizeRichText`: на `th` и `td` и только цифрами в пределах Схемы; голый конфиг их не знает вовсе. Без такой проверки `colspan="10000"` из HTML не от Редактора развернётся в 10 тыс. пустых ячеек у каждого, кто откроет Документ.
 
-Других классов, `style` (кроме произвольного цвета, см. ниже), `aria-*` и `data-*` (кроме восьми имён Схемы: `data-type` и `data-checked` чек-листа, `data-color` цвета, `data-align` выравнивания, `data-width` ширины картинки, `data-block` и `data-layout` Раскладки и `data-tone` Обёртки) в отдаваемом HTML нет. `h1` в Документе бывает только у Редактора с Инструментом `heading1` (по умолчанию в `full`); экран, у которого H1 стоит над Редактором, этот Инструмент выключает.
+Других классов, `style` (кроме произвольного цвета, см. ниже), `aria-*` и `data-*` (кроме восьми имён Схемы: `data-type` чек-листа и обёртки содержимого сворачиваемого Блока, `data-checked` чек-листа, `data-color` цвета, `data-align` выравнивания, `data-width` ширины картинки, `data-block` и `data-layout` Раскладки и `data-tone` Обёртки) в отдаваемом HTML нет. `h1` в Документе бывает только у Редактора с Инструментом `heading1` (по умолчанию в `full`); экран, у которого H1 стоит над Редактором, этот Инструмент выключает.
 
 **Картинку** Редактор пишет так: `<figure><img src="https://…" alt="…" data-width="50"><figcaption>…</figcaption></figure>`. `figcaption` есть, только когда подпись не пуста, `data-width` есть только у картинки с заданной шириной (`50`, `75` или `100` процентов ширины Документа, `RICH_TEXT_SCHEMA.imageWidths`; без него размер у картинки свой, не шире Документа), `alt` есть всегда и пуст у картинки без описания. Адрес может быть только абсолютным `http` или `https` (`RICH_TEXT_SCHEMA.imageProtocols`): `data:` (base64) и `blob:` Редактор не пишет никогда, а `style`, `width`, `height` и `class` у картинки не бывает ни у `img`, ни у `figure`. Голый `<img>` вне `figure` Редактор не отдаёт; `sanitizeRichText` его удаляет.
 
@@ -152,7 +152,7 @@ export function sanitizeDocument(html: string): string {
 
 #### Свои Инструменты: третий аргумент
 
-Если Редактор работает со своими Инструментами ([RichTextEditor, «Свой Инструмент»](../inputs/rich-text-editor.md#свой-инструмент)), сервер передаёт очистке **тот же массив `tools`**. Описание своего Инструмента — данные, и модуль с ним импортируется на сервере: очистка читает только правила Схемы (`blocks`, `marks`), Часть для движка не трогает. Чтобы в графе сервера не оказался и Tiptap, держите описание в модуле без импорта расширений — Часть для движка тогда подаётся Загрузчиком ([RichTextEditor, «Загрузчик Части для движка»](../inputs/rich-text-editor.md#загрузчик-части-для-движка)) или собирается рядом с Редактором.
+Если Редактор работает со своими Инструментами ([RichTextEditor, «Свой Инструмент»](../inputs/rich-text-editor.md#свой-инструмент)), сервер передаёт очистке **тот же массив `tools`**. Описание своего Инструмента — данные, и модуль с ним импортируется на сервере: очистка читает только правила Схемы (`blocks`, `marks`), Extensions не трогает. Чтобы в графе сервера не оказался и Tiptap, держите описание в модуле без импорта расширений — Extensions тогда подаются Загрузчиком ([RichTextEditor, «Загрузчик Extensions»](../inputs/rich-text-editor.md#загрузчик-extensions)) или собираются рядом с Редактором.
 
 ```ts
 import { sanitizeRichText } from "@olddevs/ui/editor/schema";
@@ -244,6 +244,12 @@ export default async function ArticlePage({ id }: { id: string }) {
 
 `sanitizeRichText` держит Обёртку там, где её пишет Редактор: на верхнем уровне и прямо в колонке Раскладки, не в другой Обёртке, списке, цитате и таблице; иначе Обёртка снимается, Блоки остаются подряд. Раскладка внутри Обёртки разворачивается в Блоки.
 
+## Сворачиваемый Блок
+
+Сворачиваемый Блок Редактора (Инструмент `details`, раздел «Сворачиваемый Блок» страницы [RichTextEditor](../inputs/rich-text-editor.md#сворачиваемый-блок)) в показе — **родные `details` и `summary`**: движка и JavaScript для него не нужно, раскрывает и сворачивает сам браузер, с мыши и с клавиатуры (Tab, Enter, пробел), а скринридер читает его как раскрывающийся элемент — ни ролей, ни `aria-*` кит в разметку не добавляет. Блок приходит закрытым; открытым — только тот, что сохранён с `open` (Опция `persist` Редактора). Рамка, отступ и полужирный заголовок — те же, что в Редакторе, маркер `summary` — родной маркер браузера, а Блоки содержимого идут с тем же ритмом, что в Документе. Обёртка содержимого `div[data-type="detailsContent"]` вида не имеет.
+
+`sanitizeRichText` держит Блок в форме, которую пишет Редактор: `summary` и обёртка содержимого — только прямо в `details` (иначе тег снимается, Блоки остаются подряд), `open` — только пустой и только на `details`; `iframe` так не открывается. Раскладка или Обёртка внутри содержимого разворачивается в Блоки.
+
 ## Свой Блок
 
 Свой Блок потребителя (`div[data-block="acme_card"]`, раздел «Свой Инструмент» страницы [RichTextEditor](../inputs/rich-text-editor.md#свой-инструмент)) `RichTextView` показывает очищенным HTML и даёт ему **тот же вертикальный ритм, что у абзаца, и больше ничего**: отступ до следующего Блока такой же, как у абзаца на том же месте (в Документе, цитате, ячейке, колонке). Блоки внутри своего Блока-контейнера стоят с ритмом Документа, как в Обёртке; строчное содержимое (текст, Атомы, Метки) отступов не получает. На Листе `surface="paper"` — то же.
@@ -258,7 +264,7 @@ export default async function ArticlePage({ id }: { id: string }) {
 }
 ```
 
-Вид узла из Части для движка (React-вид) в `RichTextView` не используется: движка здесь нет. Строчный Атом показывается тем, что лежит в HTML: пустой `span` без текста не виден; оживить Блок в показе можно Островом (раздел ниже). Ритм сверяет `tests/rich-text-paper-css.test.tsx` на настоящем каскаде.
+Вид узла из Extensions (React-вид) в `RichTextView` не используется: движка здесь нет. Строчный Атом показывается тем, что лежит в HTML: пустой `span` без текста не виден; оживить Блок в показе можно Островом (раздел ниже). Ритм сверяет `tests/rich-text-paper-css.test.tsx` на настоящем каскаде.
 
 ## Остров своего Блока
 
@@ -294,18 +300,18 @@ export const acmePlayer: CustomTool = {
 
 **Как это устроено и почему `RichTextView` остаётся серверным.** Так же, как у «Копировать» (раздел выше): сам компонент без состояния, клиентский кусок — отдельный файл со своей директивой.
 
-1. Описание Инструмента целиком (Часть для движка, функции) через границу RSC не пройдёт, поэтому `RichTextView` выбирает из `tools` только Острова, причём только тех Блоков, чей `data-block="<имя>"` есть в Документе (`islandsFor`, `src/editor/core/viewIsland.ts`), и отдаёт Острову ссылки на клиентские компоненты и имена атрибутов. Если нет `tools`, нет `island` у Блока или самого Блока в Документе, Острова нет вовсе: ни опорного `<template>` в разметке, ни эффекта, ни загрузки кода Острова потребителя (сервер сериализует ссылку на клиентский компонент, только когда Блок есть). `island` обязан быть компонентом из модуля с `"use client"`: серверный компонент или функция с динамическим импортом в клиентский Остров не передаются.
+1. Описание Инструмента целиком (Extensions, функции) через границу RSC не пройдёт, поэтому `RichTextView` выбирает из `tools` только Острова, причём только тех Блоков, чей `data-block="<имя>"` есть в Документе (`islandsFor`, `src/editor/core/viewIsland.ts`), и отдаёт Острову ссылки на клиентские компоненты и имена атрибутов. Если нет `tools`, нет `island` у Блока или самого Блока в Документе, Острова нет вовсе: ни опорного `<template>` в разметке, ни эффекта, ни загрузки кода Острова потребителя (сервер сериализует ссылку на клиентский компонент, только когда Блок есть). `island` обязан быть компонентом из модуля с `"use client"`: серверный компонент или функция с динамическим импортом в клиентский Остров не передаются.
 2. Серверный HTML Блока приходит всегда. До гидрации, до загрузки Острова и без JS читатель видит его — то есть содержимое Блока как оно сохранено.
 3. После монтирования Остров (`src/editor/ui/BlockIsland.tsx` и тело `BlockIslandSlots.tsx`, свой `"use client"`) находит Блоки **своего** Просмотра так же, как «Копировать» находит гнёзда: от своего опорного `<template>` влево, а не по глобальному `document` — Просмотр в теневом корне или `iframe` работает. В каждом вхождении Блока содержимое заменяется Островом; при смене `tools` (Остров пропал) или уходе Блока содержимое возвращается. Если Блок с Островом стоит внутри другого Блока с Островом, оживает внешний: компонент получает его текст целиком, а внутренний остаётся его содержимым.
 4. Состояние Острова не сбрасывается перерисовкой родителя: Остров ищет Блоки заново только когда сменился Документ, а не `tools` (инлайновый литерал массива у родителя не перемонтирует Остров). Для этого `RichTextView` держит объект `dangerouslySetInnerHTML` стабильным (`useMemo` по Документу): новый объект на каждой перерисовке заставил бы React переписать разметку вместе со вставленными Островами и кнопками «Копировать».
 
-**Остров — отдельный компонент**, а не React-вид Части для движка; Редактор поле `island` не читает.
+**Остров — отдельный компонент**, а не React-вид из Extensions; Редактор поле `island` не читает.
 
 **Цена.** Тело Острова (`BlockIslandSlots.tsx`) подключается лениво (`React.lazy`) и в первую загрузку Просмотра не входит: пока чанк идёт, виден серверный HTML Блока. В статический замер `editorView` попадает только оболочка и выбор Островов — около 0,2 кБ gzip; Tiptap в графе Просмотра по-прежнему нет, это проверяет `tests/rich-text-view.test.tsx`.
 
 ## Доступность
 
-Компонент не добавляет ролей: это обычный `div` с семантическим HTML внутри — заголовки, списки, цитата. Заголовки Документа начинаются с H2, если Редактор работал без `heading1`: страница сама держит H1. Документ с `heading1` содержит собственный `h1`, и тогда страница своего второго не ставит. H1 в `RichTextView` рисуется той же типографикой, что в Редакторе. Если Документ — отдельная область страницы, дайте контейнеру имя через `aria-label` и `role="region"`.
+Компонент не добавляет ролей: это обычный `div` с семантическим HTML внутри — заголовки, списки, цитата. Сворачиваемый Блок — родные `details` и `summary`: раскрытие с клавиатуры (Tab, Enter, пробел) и озвучивание состояния даёт браузер. Заголовки Документа начинаются с H2, если Редактор работал без `heading1`: страница сама держит H1. Документ с `heading1` содержит собственный `h1`, и тогда страница своего второго не ставит. H1 в `RichTextView` рисуется той же типографикой, что в Редакторе. Если Документ — отдельная область страницы, дайте контейнеру имя через `aria-label` и `role="region"`.
 
 ## Антипаттерны