GrMarkdown

У пропа html два значения: escape (по умолчанию) показывает разметку текстом, strip выбрасывает её. Третьего нет и не будет — оно потребовало бы v-html, которого в репозитории нет ни разу.

Это не осторожность, а следствие устройства: дерево собирается узлами Vue, а не строкой HTML, и экранирование делает сам Vue. Санитайзер в пакете отсутствует за ненадобностью — вместе с классом дефектов, ради которого его обычно ставят.

Обратная сторона названа прямо: <div> внутри markdown останется текстом. Кому нужен именно HTML, подменяет рендерер узла html через components и берёт ответственность на себя.

javascript:, data:, vbscript: и всё, чего нет в allowedProtocols, до разметки не доходят — ссылка становится обычным текстом. Проверка идёт после развёртывания сущностей и вычистки незначащих символов: javascript: и табуляция посреди схемы браузером исполняются, а наивным startsWith не ловятся.

Внешняя ссылка получает rel="nofollow noopener noreferrer"; target не навязывается — его задаёт linkTarget.

Документ делится на блоки верхнего уровня, у каждого ключ от его же исходного текста. Блок, текст которого не изменился, отдаёт тот же объект VNode, и Vue пропускает его целиком, не сравнивая и не трогая DOM.

Отсюда два свойства: правка абзаца в статье на сто килобайт стоит одного абзаца, а вставка блока в начало не пересоздаёт то, что ниже — ключ считается от текста, а не от позиции.

Виртуализация — окно отрисовки — здесь неверна: вместе с невидимыми узлами она забирает поиск по странице, переход по якорю в непоказанный раздел, выделение через весь документ и печать. Документ, в котором Ctrl+F не находит слово, документом быть перестаёт.

Поэтому в DOM живёт всё, а с блоков снимается только раскладка и отрисовка — через content-visibility. Высота каждого блока оценивается по его содержимому, иначе полоса прокрутки дёргалась бы при пролистывании.

id заголовка — слаг его текста, а не useId(). Это отступление от общего правила сделано сознательно: useId выдал бы разные идентификаторы двум рендерам одного документа, и ссылка вида #раздел из адресной строки или письма перестала бы работать.

Два документа на одной странице развести нечем, кроме idPrefix, — его и задают. headingOffset сдвигает уровни, когда документ встраивают в страницу, где h1 уже занят.

Маркер алерта разбирается только в тон. Вид сообщения — заливка, рамка, иконка, кегль — приходит из GrConfigProvider, и своего variant компонент не навязывает: иначе алерт в документе выглядел бы иначе, чем такой же алерт на странице рядом. Заголовок тона (Note, Warning, …) берётся из локали пакета — тон обязан читаться текстом, а не только цветом.

Роли живого региона у этих сообщений нет: live="off". role="alert" прерывает чтение диктором, и сообщение внутри статьи такого права не имеет.

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

Исключения сделаны там, где своя копия задавала бы визуальный контракт, принадлежащий ядру: тон и иконка сообщения, вид отметки, скролл-область и шапка таблицы — решения дизайн-системы, а не документа.

Ссылка сюда не попала по замеру, а не по вкусу: это самый частый инлайновый узел, и на документе в триста ссылок инстансы GrLink дают четырёхкратное время рендера. Кому нужен его полный контракт — ставит components.link и платит осознанно.

Алерт при этом идёт live="off": role="alert" прерывает чтение диктором, а сообщение внутри статьи такого права не имеет. Смысл тона несёт подпись текстом, а не только цвет.

Движок принимает расширения, и это единственный способ добавить синтаксис, которого нет в наборе:

const engine = createMarkedEngine({ extensions: [katexExtension] })

Берётся у расширения только токенайзер. Его renderer не вызывается никогда: разметку строит renderNodes из узлов Vue, и строки HTML в пакете не возникает вовсе. Новый тип токена приезжает узлом custom, а рисует его компонент из components по имени токена:

<GrMarkdown :source="text" :engine="engine" :components="{ inlineMath: Formula }" />

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

Так подключаются marked-katex-extension, marked-emoji, marked-directive — не заводя пакету ни одной зависимости.

Пример: выделение маркером

==текст== — выделение маркером, знакомое по Obsidian и Pandoc. Ни в CommonMark, ни в GFM такого синтаксиса нет, поэтому без расширения парсер его не узнаёт и на экране остаются сами знаки равно. Двадцать строк закрывают вопрос целиком:

import { createMarkedEngine } from '@feugene/granularity-editor/markdown'

const highlightMark = {
  name: 'highlightMark',
  level: 'inline' as const,
  start: (src: string) => src.indexOf('=='),
  tokenizer(src: string) {
    const match = /^==([^=\n]+)==/.exec(src)
    return match ? { type: 'highlightMark', raw: match[0], value: match[1] } : undefined
  },
}

const engine = createMarkedEngine({ extensions: [highlightMark] })

<script setup lang="ts">
import { h } from 'vue'

const Mark = (props: { value: string }) => h('mark', props.value)
</script>

<template>
  <GrMarkdown :source="text" :engine="engine" :components="{ highlightMark: Mark }" />
</template>

Имя компонента в components совпадает с name токена. Поля токена приходят пропами: здесь это value, у токена математики это была бы формула. Уберите компонент — и ==текст== снова станет текстом, а не исчезнет.

Ограда с языком mermaid — это обычный узел code, и рисует его тот компонент, который лежит в components.code. Пакет о mermaid не знает ни строкой и знать не будет: движок весит больше всей дизайн-системы, а платить за него обязаны были бы и документы без единой диаграммы.

Рендерер решает по языку и всё чужое отдаёт рендереру по умолчанию:

const MermaidBlock = defineComponent({
  props: { code: String, language: String, wrap: Boolean },
  setup(props) {
    // ...рисование в onMounted, см. демо на витрине
    return () => props.language === 'mermaid'
      ? h('figure', { ref: host })
      : h(GrMarkdownCode, { code: props.code, language: props.language, wrap: props.wrap })
  },
})

Три вещи в этой обвязке не косметика, и каждая стоит своих денег.

Импорт только динамический. Статический import 'mermaid' кладёт движок в общий кусок, и его скачивает каждый, кто открыл страницу с документом.

layout: 'dagre' в конфиге. Без этой строки mermaid подтягивает раскладку ELK на первый же flowchart — притом что рисует его dagre. Замер (12.0.0, что реально ушло по сети, gzip):

Одна строка конфига — минус 430 КБ и впятеро более быстрый первый кадр.

securityLevel: 'strict'. Движок строит SVG сам, и подписи в нём приходят из markdown, то есть извне. strict вычищает из них разметку; это ровно та граница, ради которой в самом пакете нет v-html.

Дальше каждый тип диаграммы платит за себя отдельно: sequence — плюс 31 КБ, class — 16 КБ, state — 14 КБ, pie — 154 КБ. Повторный показ уже загруженного типа: flowchart — 84 мс, sequence — 28 мс, class — 71 мс, pie — 16 мс. Десяток диаграмм на странице это заметная доля секунды, поэтому рисовать их лучше по мере появления в зоне видимости, а не все разом.

Нужный тип диаграммы подключать не надо

Встроенные типы — flowchart, sequence, class, state, pie, gantt, er, journey и прочие — приезжают сами: render() подтягивает грамматику того типа, который встретил, при первом же показе. Отсюда и разброс цен выше — платит тот, кто нарисовал.

Регистрация нужна только для того, чего в движке нет:

Первоисточники, они же ответ на «а как настроить вот это»:

• синтаксис всех типов диаграмм;
• конфигурация целиком — там же securityLevel и layout;
• тема и themeVariables — ими диаграмма садится на токены дизайн-системы;
• раскладки и ELK;
• API render и initialize.

Цвет для themeVariables берётся из токена в два шага, и это не прихоть: getPropertyValue отдаёт объявленное значение, а часть палитры объявлена через color-mix(); вычисленное же значение Chrome отдаёт как color(srgb …), чего разборщик цветов внутри mermaid тоже не понимает. Рабочий приём — присвоить цвет пробному элементу, прочитать вычисленный и нормализовать канвой; готовый код есть в демо на витрине.

И вторая ловушка там же: themeVariables слушается только темой base. Встроенные (default, neutral, forest, dark) задают палитру сами, и подмешивание к ним токенов даёт смесь двух решений вместо любого из них. Либо base плюс свои переменные — тогда диаграмма переключается вместе с темой страницы, — либо встроенная тема целиком.

Синтаксис mermaid — не единственный возможный: шов ничего о нём не знает. Для сравнения, nomnoml весит 24 КБ gzip и рисует за 3.4 мс, но говорит на своём языке, и написанное для mermaid он не поймёт. Выбор между ними — выбор приложения, а не пакета; менять придётся один компонент.

Три значения, и отличаются они тем, что вообще считается разметкой, а не тем, как она выглядит.

gfm (по умолчанию) — таблицы, списки задач, зачёркивание, автоссылки. commonmark — без них: строка ~~текст~~ останется тильдами, а | таблицей не станет. minimal — то же самое плюс картинка превращается в свою подпись.

Последнее нужно там, где текст пишет посторонний. Удалённая картинка в комментарии — это запрос к чужому серверу, то есть пиксель слежения и утечка IP читателя; а размер её потребитель не контролирует, и вёрстка страницы едет от одной строки. Выбрасывать картинку молча было бы хуже: пропавшая иллюстрация оставляет читателя гадать, что там было. Поэтому от неё остаётся её alt — обычным текстом в потоке.

Пресет не отключает блок кода и не трогает оформление: и то и другое — работа components и токенов.

interactiveTasks включает чекбоксы списка задач. Эмит taskToggle несёт офсет маркера в исходнике, а не номер пункта: сопоставлять задачи по порядку значит промахнуться на первом же вложенном списке. Приложение переписывает markdown по офсету и отдаёт новый source.

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

Рисует их GrCheckbox ядра. Своя копия его вида разошлась бы с дизайн-системой молча, а нативный <input> браузер рисует сам: в состоянии disabled гасит по-своему и растягивается флексом в неквадрат.

Без interactiveTasks чекбокс идёт readonly, а не disabled: документ показывает состояние задачи, а не запрещает её, и отметка остаётся в полном цвете.

Имя чекбокса — текст его пункта: aria-labelledby указывает на первый блок пункта. Общее «Task» у всех диктор читал бы одинаково, и задачи было бы не различить. Вложенный список в имя родителя не входит — там чужие задачи со своими именами. Пункт без текста — пустой инлайн, картинка без подписи — называется переведённым «Task», а не пустым именем. Идентификаторы подписей берутся из useId() экземпляра, поэтому два одинаковых документа на странице их не делят.

Блок с задачами при interactiveTasks — единственный, кого правка выше заставляет перерисоваться. Ключ кэша считается от текста, и сдвинутый блок узнаётся как тот же, а офсет маркера запечатан в обработчике чекбокса: из кэша он пришёл бы от прежнего исходника, и переключение задачи переписало бы чужие символы. При streaming хвост разбирается отдельно, и офсеты его задач сдвигаются к началу исходника — taskToggle всегда указывает в полный текст.

Слот caret при streaming встаёт внутрь последнего инлайнового ряда, а не отдельной строкой под блоком: так он читается как «здесь продолжается набор», а не как опечатка. Хвостом считается то, что поток дописывает прямо сейчас, — последний пункт списка, последняя ячейка таблицы, заголовок, последний блок цитаты или алерта. Блок кода и подменённые через components рендереры курсор не принимают: у них своя разметка, и вставлять в неё чужой узел нельзя. Обёртка курсора aria-hidden: он декоративный, и диктор не читает его ни в абзаце, ни в имени задачи.

• не редактор: компонент показывает и ничего не меняет в источнике сам. Правка форматированного текста — GrRichText, правка markdown как кода — GrCodeEditor из granularity-code;
• без подсветки кода в составе: блок кода нарисован со своей рамкой, ярлыком языка и копированием, но не раскрашен. Подсветка приходит пропом components.code — своя или GrCodeBlock;
• без математики и диаграмм в составе: $…$ и блок mermaid из коробки остаются текстом. Обе вещи тянут сотни килобайт, и место им в расширении — подключаются они разделом выше, а пакет за них не платит;
• частотная таблица сущностей: развёрнуты числовые формы и около сорока имён. Редкое имя останется записью — полная таблица весит больше самого компонента.