GrRichText

Отдельного санитайзера в пакете нет, и это не упущение. ProseMirror разбирает вход по схеме: узел или марка, которых в ней нет, отбрасываются при разборе, а на выход документ сериализуется из того же дерева. <script>, <iframe> и <img> не переживают вставки — проверено тестом, а не обещано.

Отсюда следствие, которое стоит знать: чего нет в схеме, того не будет и в значении. Вставили статью с картинками в поле со схемой minimal — останется текст. Это осознанный размен: поле, принимающее произвольную разметку, ломает вёрстку страницы, на которой её потом покажут.

minimal — начертание, ссылка, список. article добавляет структуру: заголовки, цитату, блок кода.

Заголовка первого уровня не даёт ни одна. h1 на странице один и принадлежит ей, а не полю ввода внутри неё; редактор, позволяющий вставить второй, ломает структуру документа у того, кто просто печатал текст.

Кнопки строятся по списку действий самой схемы. Напиши их руками — и первая же правка схемы разошлась бы с панелью молча: кнопка осталась, а команды за ней больше нет.

Панель переносится группами целиком, а не кнопка за кнопкой. flex-wrap по отдельным кнопкам рвал бы ряд там, где кончилось место, и разлучал бы кнопки одного смысла: «Заголовок» в одной строке, «Подзаголовок» в другой, причём без разделителя между ними. Обёртка группы этого не допускает — на узком поле строки читаются теми же блоками, что и один ряд.

Тулбар — role="toolbar" с одной остановкой Tab: внутри ходят стрелками. Иначе до самого текста пришлось бы добираться десятком нажатий — у «статьи» десять кнопок. Активный формат объявлен aria-pressed, а не только подсветкой: подсветка для скринридера не существует.

toolbar="bubble" ставит панель у выделения, "both" — и сверху, и у выделения.

Пузырёк живёт ровно пока в поле есть непустое выделение и фокус: ухода фокуса достаточно, чтобы он погас. Отсюда два неочевидных следствия, и оба сидят в коде:

• панель не забирает фокус при открытии — иначе гасила бы себя в том же кадре, в котором открылась;
• кнопка пузырька отменяет mousedown. Без этого фокус уходил бы на кнопку, и пузырёк исчезал под курсором после первого же формата — второй подряд применить нечем. Панели сверху это не нужно: она от фокуса не зависит.

Кнопки пузырька — всегда самой мелкой ступени, независимо от размера поля. Панель сверху живёт в раме поля и растёт вместе с ним, а пузырёк висит над текстом, который читают, и там уместна наименьшая площадь, дающая цель нажатия 28×28 — выше требуемых WCAG 2.2 двадцати четырёх. Есть и арифметическая причина: панель поповера ограничена по ширине, и десяток кнопок ступени поля в неё не помещался.

Esc пузырёк закрывает, клик вне — нет: слушать пришлось бы click, а именно им заканчивается протяжка выделения, и панель закрывалась бы ровно в тот момент, когда должна появиться.

Якорь пузырька — прямоугольник выделения в координатах вьюпорта, а прокрутка колесом выделение не меняет. Поэтому, пока пузырёк включён, якорь пересчитывается на scroll и resize — scroll слушается в фазе захвата на window, чтобы ловить и прокрутку вложенной области, а не только страницы. Выделение, ушедшее за видимую часть поля или страницы, пузырёк прячет, а не оставляет висеть над чужим содержимым; вернулось — пузырёк снова рядом. Закрытый Esc пузырёк прокрутка не возвращает.

Видимая часть урезается и scroll-padding каждой области прокрутки, страницы тоже: так сайт объявляет липкую шапку (html { scroll-padding-top: 80px }). Выделение под шапкой пузырёк прячет; у самой её кромки, где над выделением места нет, пузырёк встаёт под ним, а не на шапку. Сторону выбирает поле — GrPopover о scroll-padding не знает и отступает только от края вьюпорта.

Показывать ли и с какой стороны — два разных вопроса с двумя разными областями. Видно ли выделение, решают все обрезающие предки, поле включительно: выделение, уехавшее за край своей прокрутки, пузырёк прячет. А место для пузырька — страница вне поля: пузырёк живёт в верхнем слое, и поле его не обрезает. Своя прокрутка поля (.ProseMirror с overflow-y: auto) и его рамка в счёт не идут — пузырёк ложится на тулбар и поле над первой строкой, а вниз уходит, только когда над выделением нет места на странице, например у липкой шапки. Иначе он закрывал бы следующую строку, которую читают.

Клавиатурный путь к форматам в этом режиме — горячие клавиши: панель у выделения остановкой Tab не является. Нужны обе дороги — toolbar="both".

Слоты #header и #footer дают полосы над областью ввода и под ней, внутри той же рамки:

<GrRichText v-model="value">
  <template #header>Кому: <strong>[email protected]</strong></template>
  <template #footer>Знаков: {{ length }}</template>
</GrRichText>

Раньше зон было ровно две — тулбар и текст, — поэтому подпись со счётчиком ставили снаружи рамки. Визуально они оказывались отдельным элементом: рамка обводила только текст, и связь с полем держалась на близости, а не на разметке.

Зоны отбиты рамкой изнутри, как тулбар, — линия принадлежит границе между зонами, а не самой зоне: у края поля она сошлась бы со скруглением рамки. Фона у них нет намеренно: --gr-muted подложен тулбару, потому что он панель управления, а здесь содержимое потребителя, и вторая подложка спорила бы с ним.

Клавиатура зон — забота потребителя: тулбар водит фокус ровером по своим кнопкам, а что положено в шапку, компонент не знает.

output="html" (по умолчанию) — строка разметки; output="json" — документ TipTap. Тот же приём, что у valueAdapter в granularity-chrono: форму значения выбирает потребитель, а не поведение пользователя.

В нативную форму значение уходит строкой в любом режиме: скрытое поле не умеет объектов.

Поле нужно, пока текст правят. Показать сохранённое оно — не лучший выбор: ProseMirror требует DOM, поэтому на сервере не печатается ничего (см. следующий раздел), а в браузере ради одного абзаца поднимается редактируемый документ с плагинами, транзакциями и историей.

Документ TipTap переводится в markdown и отдаётся GrMarkdown:

<script setup lang="ts">
import { computed } from 'vue'
import { markdownFromEditorDocument } from '@feugene/granularity-editor/markdown'
import GrMarkdown from '@feugene/granularity-editor/components/GrMarkdown'

const { document } = defineProps<{ document: object }>()
const source = computed(() => markdownFromEditorDocument(document))
</script>

<template>
  <GrMarkdown :source="source" />
</template>

Потерь на этом пути нет ни у одной из схем. Сериализатор знает каждый узел и каждую марку, которые они способны выдать, — вплоть до переноса строки по Shift+Enter; картинку он тоже сериализует, хотя ни одна схема её пока не даёт. Заводя своё расширение с новым узлом, ветку в сериализаторе придётся завести вместе с ним: молча потеряется именно то, что вы добавили.

Он же годится и для хранения: output="json" держит документ TipTap, а markdownFromEditorDocument кладёт в базу markdown — форму, которую прочтёт и человек, и любой другой инструмент.

ProseMirror требует DOM, поэтому редактор поднимается после монтирования, а серверная разметка — оболочка с data-allow-mismatch. Текста в ней нет, но место есть: хост держит болванку с тем же боксом, что займёт область ввода, — высоты --gr-rich-text-min-height и --gr-rich-text-max-height у них общие, одним правилом. Поле с min = max на гидрации не двигается; значение выше min-height при открытом max-height вырастает под текст после монтирования — см. ../ssr.md.

v-html в пакете нет намеренно: печатать чужую разметку ради первого кадра значило бы завести единственную XSS-поверхность ровно там, где данные приходят от пользователя. Поле — это ввод, а не публикация.

extensions добавляет расширения TipTap к схеме, а не заменяет её:

<script setup lang="ts">
import { CharacterCount } from '@tiptap/extensions'
</script>

<template>
  <GrRichText v-model="text" :extensions="[CharacterCount.configure({ limit: 500 })]" />
</template>

Готовые расширения перечислены в каталоге TipTap, своё пишется по руководству. Пакет их не оборачивает: что отдали, то и получит редактор.

Смена набора — как и смена schema — пересобирает редактор: схема ProseMirror неизменяема, из неё выведены и документ, и команды. Текст переносится разметкой и проходит разбор заново, поэтому узел, которого в новой схеме нет, отбрасывается — то же правило, что и при вставке.

Кнопку для своего расширения тулбар не покажет: он строится по схеме, и кнопка без команды за ней была бы обманом. Своя кнопка ставится слотом #action-<key> либо собственной панелью поверх инстанса из defineExpose.

• не CMS: ни картинок, ни упоминаний, ни таблиц в этом релизе. Расширение TipTap потребитель добавляет сам через extensions, а инстанс редактора компонент отдаёт через defineExpose. Кнопку для своего расширения тулбар не покажет: он строится по схеме, а не по набору расширений;
• без совместного редактирования: одновременная правка двумя людьми требует транспорта и разрешения конфликтов, а это не задача поля ввода.