@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/components/content/carousel.md

@@ -0,0 +1,227 @@
+---
+component: Carousel
+exports: [Carousel, CarouselProps, CarouselSlidesPerView]
+category: content
+status: stable
+source: src/components/content/Carousel.tsx
+story: src/components/content/Carousel.stories.tsx
+---
+
+# Carousel
+
+## Кратко для AI
+
+Лента слайдов на нативной прокрутке с CSS scroll-snap: листают кнопки «назад»
+и «вперёд», колесо мыши, тачпад, свайп и стрелки клавиатуры; слайд после жеста
+встаёт ровно. Имя региона обязательно: ровно одно из `aria-label` и
+`aria-labelledby`. Сколько
+слайдов в кадре — `slidesPerView` (число или объект по брейкпойнтам кита), текущий
+слайд — `index` / `defaultIndex` / `onIndexChange`. Слайды сами не
+переключаются никогда: ни автопрокрутки, ни бесконечной ленты.
+
+## Когда использовать
+
+- Галерея, подборка или набор карточек, которые должны занять одну строку
+  экрана, а не расти вниз: превью, рекомендации, шаги знакомства.
+- Нужно показывать несколько слайдов разом и менять их число по ширине экрана
+  (`slidesPerView={{ base: 1, md: 2, xl: 4 }}`).
+- Нужно связать ленту с остальным экраном: подпись, миниатюры, счётчик — через
+  `index` и `onIndexChange`.
+- Компонент «на будущее» (ADR-0048): заказчика при выпуске не было, API взят по
+  аналогам — shadcn/ui `Carousel`, Mantine `Carousel`, Chakra `Carousel`, Ant
+  `Carousel`, Fluent 2 `Carousel`. Ваш экран первым проверит этот API: если он
+  потребует другого API, это не нарушение контракта.
+
+## Когда не использовать
+
+- Автоматически сменяющиеся слайды, бесконечная лента, точки-индикаторы — их
+  нет и не будет: кит не берёт на себя ни кнопку паузы, ни ловушки доступности
+  автопрокрутки (движение нельзя остановить, текст не успевают прочитать).
+- Готовый компонент-лайтбокс: отдельного нет и не будет, но просмотр
+  листаемым окном собирается из `Dialog` и `Carousel` — см.
+  [«Просмотр каруселью в `Dialog`»](#просмотр-каруселью-в-dialog).
+- Для вкладок с одним видимым содержимым используйте `Tabs`: у них иная семантика
+  (`tablist`), а не лента.
+- Постраничный просмотр записей со стрелками и клавишами — отдельная задача
+  (`DetailPager` в реестре кандидатов), не карусель.
+- Если набор уместно показать сеткой целиком, берите `Grid`: скрыть половину
+  содержимого за прокруткой — плата, которую платят только когда сетка не
+  помещается.
+- Для длинного списка строк используйте `Table` или список; горизонтальная лента
+  для него — неверный способ показа.
+
+## Минимальный пример
+
+```tsx
+import { Carousel } from "@olddevs/ui";
+
+<Carousel aria-label="Рекомендации" slidesPerView={{ base: 1, md: 3 }}>
+  <ProductCard id="a" />
+  <ProductCard id="b" />
+  <ProductCard id="c" />
+  <ProductCard id="d" />
+</Carousel>;
+```
+
+## Public API
+
+| Проп               | По умолчанию | Значение                                                                                                       |
+| ------------------ | ------------ | -------------------------------------------------------------------------------------------------------------- |
+| `aria-label`       | —            | Имя региона строкой. Обязательно ровно одно из `aria-label` и `aria-labelledby`; оба сразу — ошибка типа.      |
+| `aria-labelledby`  | —            | Имя региона от видимого заголовка над лентой — `id` заголовка.                                                 |
+| `slidesPerView`    | `1`          | `1`, `2`, `3` или `4` слайда в кадре; объект `{ base, sm, md, lg, xl }` — своё число, начиная с каждой ширины. |
+| `index`            | —            | Текущий слайд, управляемый режим: левый видимый, с нуля.                                                       |
+| `defaultIndex`     | `0`          | Слайд при первом показе, неуправляемый режим. Открывается без анимации.                                        |
+| `onIndexChange`    | —            | `(index: number) => void` — лента остановилась на другом слайде.                                               |
+| `children`         | —            | Слайды: каждый прямой потомок — один слайд.                                                                    |
+| атрибуты `section` | —            | `className`, `id`, `data-*` доходят до региона; `ref` — на `<section>` (`forwardRef`).                         |
+
+**Слайд — прямой потомок.** Фрагмент — один потомок, поэтому слайды внутри него
+не становятся отдельными слайдами; `null`, `false` и пустые строки слайдом не становятся.
+
+**Зазора между слайдами нет.** Ширина слайда — доля строки, и зазор сделал бы её
+зависимой от числа слайдов в кадре. Отступ между карточками — внутренний отступ
+содержимого слайда (`p-2` на корне карточки).
+
+### Индекс — левый видимый слайд
+
+При `slidesPerView={3}` и пяти слайдах достижимы индексы 0–2: лента не едет
+дальше своего конца, в последнем кадре слайды с индексами 2–4. Индекс, которого достичь
+нельзя (`index={4}` в этом примере), лента заменяет ближайшим достижимым.
+
+### `onIndexChange` — после остановки
+
+Колбэк вызывается, когда прокрутка остановилась (через 100 мс после последнего
+события прокрутки), а не на каждый кадр. Поэтому в управляемом режиме смена
+`index` снаружи не порождает эхо: лента едет к назначенному слайду, проходит
+промежуточные молча, и на месте колбэк не вызывается — слайд уже тот.
+
+Управляемый режим — в обычном смысле: `index` назначает слайд, колбэк просит
+родителя его сменить. Родитель, оставивший прежний индекс, получит ленту обратно
+на нём — плавно, после остановки. Слайд, который назначили сами (`index`,
+`defaultIndex`), колбэка не вызывает.
+
+### Кнопки и края
+
+Кнопки — `Button` кита, только иконка; имена из каталога сообщений («Предыдущий
+слайд», «Следующий слайд»). На краях выключаются; если вся лента помещается в
+кадр, выключены обе. Нажатая кнопка, ставшая выключенной, передаёт фокус
+соседней — пользователь клавиатуры не оказывается в начале страницы. Если нажать
+несколько раз подряд, каждое нажатие отсчитывается от слайда, к которому лента
+уже едет.
+
+### Плавность и `prefers-reduced-motion`
+
+Кнопки листают с `behavior: "smooth"`, а при `prefers-reduced-motion: reduce` —
+мгновенно. Предпочтение читается в момент прокрутки. Остановка на слайде после
+жеста — встроенная привязка браузера, её анимацию ведёт браузер.
+
+## Просмотр каруселью в `Dialog`
+
+Лайтбокс — не компонент, а компоновка: `Dialog` даёт окно, фокус и возврат
+фокуса, `Carousel` — листание. Новых экспортов она не требует. Открытием
+отдельного слайда занимается вызывающий код: он запоминает индекс и список слайдов на
+момент открытия, `Dialog` показывает их, а `Carousel` стартует с нужного места
+через `defaultIndex`.
+
+```tsx
+import { Carousel, Dialog, Image } from "@olddevs/ui";
+
+const [view, setView] = useState<{ start: number; files: MediaFile[] } | null>(null);
+const [index, setIndex] = useState(0);
+
+const open = (start: number) => {
+  setIndex(start);
+  // Список замораживается при открытии: загрузка, пришедшая позже, не должна
+  // сдвинуть слайды под пальцем.
+  setView({ start, files });
+};
+
+<Dialog
+  open={view !== null}
+  onClose={() => setView(null)}
+  title={view?.files[index]?.name ?? "Просмотр"}
+  subtitle={view ? `${index + 1} из ${view.files.length}` : undefined}
+  className="w-full max-w-[720px]"
+>
+  {view && (
+    <Carousel aria-label="Файлы" defaultIndex={view.start} onIndexChange={setIndex}>
+      {view.files.map((file) => (
+        <Image key={file.id} src={file.url} alt={file.name} ratio={16 / 9} fit="contain" />
+      ))}
+    </Carousel>
+  )}
+</Dialog>;
+```
+
+Что здесь важно:
+
+- **`defaultIndex`, а не `index`.** Окно монтирует содержимое при открытии,
+  поэтому лента каждый раз стартует с `view.start` без анимации. Управляемый
+  `index` нужен, только если слайд меняется и снаружи (миниатюры, кнопки в
+  шапке).
+- **Заголовок и счётчик идут от `onIndexChange`.** Колбэк срабатывает после
+  остановки ленты, а не на каждый кадр — заголовок меняется, когда слайд встал.
+  Имя окна остаётся именем `Dialog` (`title`), а имя слайда «N из M» лента
+  объявляет сама.
+- **`{view && …}` внутри окна.** Пока `view` пуст, ленты нет вовсе: следующее
+  открытие создаёт её заново и не наследует прежнюю прокрутку.
+- **Слайд со своим подписанным содержимым.** `alt` у изображения — имя файла:
+  имя слайда «N из M» его не заменяет.
+- Фокус: открытие кладёт его в окно, `Escape` закрывает и возвращает туда,
+  откуда окно открыли. Стрелки листают, когда фокус на ленте; кнопки ленты —
+  отдельные табстопы.
+
+Открывать окно удобно по `onAction` у [`VirtualGrid`](virtual-grid.md): клик и
+Enter по ячейке вызывают `open`, не выделяя её.
+
+## Доступность
+
+Паттерн WAI-ARIA APG Carousel (без автопрокрутки, поэтому без кнопки паузы).
+
+- Регион — `<section>` с `aria-roledescription` «carousel» (в русской локали
+  «карусель») и именем из `aria-label` или `aria-labelledby`. Без имени
+  скринридер объявит безымянный регион, поэтому имя требует тип. Пропа `label`
+  у карусели нет: в ките `label` — только видимая подпись
+  ([conventions.md](../../conventions.md#доступное-имя)).
+- Слайд — `role="group"` с `aria-roledescription` «slide» («слайд») и именем
+  «N из M» из каталога: скринридер читает «слайд, 2 из 5». Слова
+  `aria-roledescription` — текст, который озвучивает скринридер, поэтому они в каталоге сообщений, а
+  не токен ARIA.
+- Слайды вне кадра от скринридера **не скрываются**: без автопрокрутки лента
+  читается целиком, а когда фокус попадает на слайд вне кадра, браузер докручивает ленту до этого
+  слайда сам.
+- Клавиатура: Tab доходит до кнопки «назад», ленты и кнопки «вперёд»; выключенные кнопки на краях в обход не входят. На
+  сфокусированной ленте стрелки листают встроенной прокруткой, с привязкой. Если в
+  слайдах есть ссылки и кнопки, Tab по ним докручивает ленту к слайду.
+- Лента получает `tabIndex={0}`: прокручиваемый блок без места в обходе — нарушение
+  axe `scrollable-region-focusable`.
+- Подписи слайдам по смыслу («Фото 2: закат») задавайте содержимым — имя слайда
+  «N из M» их не заменяет.
+- В RTL листание и стрелки на кнопках зеркалятся.
+
+## Антипаттерны
+
+- Класть в слайды интерактивные формы, которые нельзя пройти без листания:
+  скрытое за краем не видно и не найти глазами.
+- Задавать `slidesPerView` числом вне набора 1–4 (`slidesPerView={5}`) или
+  собирать класс ширины самому — набор закрыт, класс на каждое значение написан
+  в исходнике.
+- Собирать лайтбокс не из `Dialog`, а на `ModalOverlay` или на своей подложке:
+  теряются имя окна, ловушка фокуса и возврат фокуса.
+- Менять `index` из таймера, чтобы «оживить» ленту: автосмена — то, чего
+  компонент не делает по замыслу, и пользователь не успевает прочитать.
+- Выводить число слайдов из значения `index` при `slidesPerView > 1`: индекс — левый
+  видимый слайд, а не «страница».
+
+## Связанные исходники и Storybook
+
+- Исходник: `src/components/content/Carousel.tsx`; словарь «значение по брейкпойнтам →
+  классы» — внутренний `src/lib/responsive.ts` (не public API).
+- Тесты: `tests/carousel.test.tsx` (имена, кнопки, края, `onIndexChange`,
+  режимы; прокрутка подменена, потому что jsdom не считает раскладку);
+  привязка к слайду, жест и ширина слайда на брейкпойнтах — ручная проверка
+  витрины в браузере; каждый класс ширины в собранном CSS —
+  `tests/class-coverage.test.ts`.
+- История: `src/components/content/Carousel.stories.tsx`. Уровень — ядро (ADR-0014): своя
+  модель доступности и своё поведение прокрутки.

package/docs/components/content/code-view.en.md

@@ -0,0 +1,177 @@
+---
+component: CodeView
+exports: [CodeView]
+category: content
+status: stable
+source: src/components/content/CodeView.tsx
+story: src/components/content/CodeView.stories.tsx
+sourceHash: 012cd9a30845
+---
+
+# CodeView
+
+## Summary for AI
+
+`CodeView` is a code viewer: a JSON API response, a YAML config, a webhook body. **It does not highlight by itself**: `code` is required plain text, `children` is optional markup. The kit's highlighting, with the same theme as in the Editor, comes from `highlightCodeNodes(code, language)` in `@olddevs/ui/editor/highlight` — put its result into `children`; you can also bring your own highlighter.
+
+## When to use
+
+- You need to show code or data as is: an API response, a configuration, a filter expression.
+- The user needs to copy it whole.
+
+## When not to use
+
+- The code has to be **edited** — that is a different component, not an axis of this one. A code editor requires Monaco or CodeMirror, and the conversation starts with a decision, not with a prop.
+- If you show a short identifier inline, use `Kbd` or `CopyButton` next to the text.
+
+## Minimal example
+
+```tsx
+<CodeView code={JSON.stringify(response, null, 2)} title="response.json" copyable lineNumbers />
+```
+
+With the kit's highlighting — the helper from the `@olddevs/ui/editor/highlight` entry point (the "Kit highlighting" section):
+
+```tsx
+import { highlightCodeNodes } from "@olddevs/ui/editor/highlight";
+
+<CodeView code={source} title="main.py" copyable>
+  {highlightCodeNodes(source, "python")}
+</CodeView>;
+```
+
+With your own highlighter — also as **nodes**, not an HTML string:
+
+```tsx
+// Shiki: codeToHast + hast-to-jsx. Prism: tokenize. Both return nodes.
+<CodeView code={source} title="response.json" copyable>
+  {highlightToNodes(source)}
+</CodeView>
+```
+
+## Public API
+
+- `code` — **always required**, even when markup is passed. The line count is computed from it, and the content to copy is taken from it.
+- `children` — highlighted markup: the kit's `highlightCodeNodes` or your own highlighter; without it, `code` is rendered as is.
+- `title` — the panel title; without it and without `copyable` there is no header at all.
+- `copyable` — a copy button in the header, the ready-made `CopyButton`.
+- `lineNumbers` — line numbering. Works **only with plain `code` and only without `wrap`**: see below.
+- `wrap` — wraps long lines; without it there is horizontal scrolling, and the scroll area is keyboard-focusable.
+
+## Trust boundary: the consumer is fully responsible for the markup
+
+`children` is rendered as is, through the ordinary React path. The caveat is
+needed because the main highlighter APIs return an **HTML string**, not nodes:
+Shiki `codeToHtml`, Prism `highlight`, highlight.js `highlightAuto().value`.
+The only way to put such a string here is `dangerouslySetInnerHTML`.
+
+Then the consumer alone decides whether the markup can be trusted, while `code` in this
+component is usually **untrusted**: ADR-0039 itself names its scenarios — an API
+response, a webhook body. Sanitization is not part of the highlighter or of
+the kit.
+
+The safe path is nodes, not a string: the kit's `highlightCodeNodes`, Shiki's
+`codeToHast`, Prism's `Prism.tokenize`. The examples above are written exactly
+this way.
+
+## Size limit
+
+`lineNumbers` renders one DOM node per line. Measured: a megabyte of code is 4 nodes without
+numbering and more than fifteen thousand with it, and the main thread is
+noticeably blocked. On files of thousands of lines, turn numbering off; the consumer
+truncates an input that is too large itself: the component is a viewer, not
+an editor, and has no virtualization.
+
+## Kit highlighting
+
+`highlightCodeNodes(code, language)` from the `@olddevs/ui/editor/highlight`
+entry point colors code with the same grammar and the same theme as the code block in
+the [Editor](../inputs/rich-text-editor.md) and [`RichTextView`](rich-text-view.md):
+GitHub Light in the `light` theme, GitHub Dark in `dark` and `dim`. The theme
+follows the nearest ancestor with `data-theme`, so `CodeView` on a nested light
+Paper (`surface="paper"`) inside a dark app is light.
+
+```tsx
+// A server component: highlighting does not end up in the client bundle.
+import { CodeView } from "@olddevs/ui";
+import { highlightCodeNodes } from "@olddevs/ui/editor/highlight";
+
+export function Webhook({ body }: { body: string }) {
+  return (
+    <CodeView code={body} title="payload.yaml" copyable>
+      {highlightCodeNodes(body, "yaml")}
+    </CodeView>
+  );
+}
+```
+
+- **Languages** — the same as in the Editor: Python, TypeScript, JavaScript, Go,
+  HTML, JSON, YAML, Markdown. Case and spaces do not matter, aliases (`py`, `ts`,
+  `js`, `golang`, `htm`, `yml`, `md`) are resolved to the name. For an unknown
+  language and for empty code the helper returns `null`: `children` is empty,
+  and `CodeView` renders the code as is — with line numbers, if they are on.
+- **Nodes, not a string.** Code becomes React text nodes, tokens become `span`
+  with `hljs-…` classes; markup inside the code stays text. The helper has no
+  hooks and no `"use client"`: it can be called in both a server component and a client
+  component.
+- **The block background belongs to the highlight theme.** GitHub colors do not
+  reach a 4.5:1 contrast ratio on the kit's code backing, so under the kit's tokens the code area
+  takes the theme background. The helper puts a `data-code-highlight` marker on
+  the token root, and `CodeView` turns the background on only when it is present: markup from
+  your own highlighter, even with the same `hljs-…` classes, is not recolored.
+- **There are no line numbers with highlighting** — by the same rule as for any
+  markup (the section below).
+- **Cost.** `CodeView` itself and the main `@olddevs/ui` entry point do not import the
+  highlighter. Lowlight, the highlight.js core and eight grammars — 22.6 kB
+  gzip — are included only for whoever imports `@olddevs/ui/editor/highlight`; you need
+  to install `lowlight` and `highlight.js` for it (Editor engine packages,
+  not in the kit's manifest).
+
+Why a helper and not a `language` prop: there is no conditional import, and a
+prop would keep the highlighter in the main entry point's graph for every consumer of
+the kit. The boundary is
+ADR-0039,
+narrowed by ADR-0052.
+
+Your own highlighter (Shiki, Prism) still goes into `children` — then the
+consumer chooses the theme and background, and the kit does not touch them.
+
+## Why `code` is required even with markup
+
+Copying takes the string, not the DOM. Copying from the markup would drag line
+numbers and highlight token boundaries into the clipboard — that is, text that
+does not compile.
+
+For the same reason the line count is computed from `code`: a gutter that derives its line count
+from the markup drifts from the content on the first highlighter that
+wraps a line in two elements.
+
+## Line numbers are not supported with markup or wrapping
+
+With `children` the gutter is not rendered at all, and this is deliberate. The
+kit does not know where the line boundaries are in third-party markup: a highlighter
+is free to wrap a line in any number of elements. A number next to
+the wrong line is worse than no number.
+
+With `wrap`, the reason is the same but the mismatch comes from a different source: a
+wrapped line takes two or more visual lines in the text and still one in the number
+column. The number lands next to the wrong line, and the last line of code is
+left without a number altogether.
+
+All trailing line breaks are trimmed when counting: a file read from disk almost
+always ends with at least one, sometimes two. Otherwise each such line break would add an extra
+number for an empty line at the end.
+
+## What the kit still does
+
+What the highlighter does not solve and what every consumer would otherwise
+write from scratch: wrapping or scrolling instead of clipping, line numbering, a
+monospaced font from a typography token, and copying with the ready-made
+`CopyButton`.
+
+## Accessibility and semantics
+
+- Line numbers are `aria-hidden` and `select-none`: in speech they are noise, because every line would start with a number, and in the clipboard they are junk. The number column sticks to the left edge: otherwise, when scrolling right, it slides off the edge exactly when it is needed most.
+- The horizontal scroll area is focusable (`tabindex="0"`): the keyboard cannot reach content that scrolls only with a pointer — the axe rule `scrollable-region-focusable`.
+- The token colors of the kit's highlighting are the GitHub theme, shared with the Editor; axe measures the contrast of each token role in all three themes (the `KitHighlighting` story in `src/editor/CodeViewHighlighting.stories.tsx`). The kit does not color the markup of your own highlighter.
+- See `src/components/content/CodeView.tsx`, `src/components/content/CodeView.stories.tsx`, `tests/code-view.test.tsx`; the kit's highlighting — `src/editor/features/code/highlightNodes.ts`, `src/editor/CodeViewHighlighting.stories.tsx`, `tests/code-view-highlight.test.tsx`.

package/docs/components/content/code-view.md

@@ -0,0 +1,172 @@
+---
+component: CodeView
+exports: [CodeView]
+category: content
+status: stable
+source: src/components/content/CodeView.tsx
+story: src/components/content/CodeView.stories.tsx
+---
+
+# CodeView
+
+## Кратко для AI
+
+`CodeView` показывает код: JSON ответа, YAML конфига, тело вебхука. **Сам подсветку не делает**: `code` — обязательный простой текст, `children` — необязательная разметка. Подсветку кита той же темой, что в Редакторе, даёт `highlightCodeNodes(code, language)` из `@olddevs/ui/editor/highlight`. Её результат кладут в `children`, а можно принести и свой подсветчик.
+
+## Когда использовать
+
+- Надо показать код или данные как есть: ответ API, конфигурацию, выражение фильтра.
+- Пользователю нужно это скопировать целиком.
+
+## Когда не использовать
+
+- Код надо **редактировать** — это другой компонент, а не ось у этого. Редактор кода требует Monaco или CodeMirror, и разговор начинается с решения, а не с пропа.
+- Показывается короткий идентификатор в строке — это `Kbd` или `CopyButton` рядом с текстом.
+
+## Минимальный пример
+
+```tsx
+<CodeView code={JSON.stringify(response, null, 2)} title="response.json" copyable lineNumbers />
+```
+
+С подсветкой кита — хелпер из входа `@olddevs/ui/editor/highlight` (раздел «Подсветка кита»):
+
+```tsx
+import { highlightCodeNodes } from "@olddevs/ui/editor/highlight";
+
+<CodeView code={source} title="main.py" copyable>
+  {highlightCodeNodes(source, "python")}
+</CodeView>;
+```
+
+Со своим подсветчиком — тоже **узлами**, а не строкой HTML:
+
+```tsx
+// Shiki: codeToHast + hast-to-jsx. Prism: tokenize. Оба отдают узлы.
+<CodeView code={source} title="response.json" copyable>
+  {highlightToNodes(source)}
+</CodeView>
+```
+
+## Public API
+
+- `code` — **обязателен всегда**, даже когда передана разметка. Из него считается число строк и берётся содержимое для копирования.
+- `children` — подсвеченная разметка: `highlightCodeNodes` кита или свой подсветчик; без неё выводится `code` как есть.
+- `title` — заголовок панели; без него и без `copyable` шапки нет вовсе.
+- `copyable` — кнопка копирования в шапке, готовая `CopyButton`.
+- `lineNumbers` — нумерация строк. Работает **только с простым `code` и только без `wrap`**: см. ниже.
+- `wrap` — перенос длинных строк; без него горизонтальная прокрутка, и область прокрутки фокусируема с клавиатуры.
+
+## Граница доверия: разметка целиком на потребителе
+
+`children` рендерится как есть, обычным путём React. Оговорка нужна потому, что
+основные API подсветчиков отдают **строку HTML**, а не узлы — Shiki `codeToHtml`,
+Prism `highlight`, highlight.js `highlightAuto().value`. Единственный способ
+поместить такую строку сюда — `dangerouslySetInnerHTML`.
+
+Тогда потребитель сам решает, можно ли доверять разметке, а `code` в этом компоненте
+обычно **недоверенный**: ADR-0039 сам называет его сценарии — ответ API, тело
+вебхука. Санитизация не входит ни в подсветчик, ни в кит.
+
+Безопасный путь — узлы, а не строка: `highlightCodeNodes` кита, `codeToHast` у
+Shiki, `Prism.tokenize` у Prism. Примеры выше написаны именно так.
+
+## Потолок размера
+
+`lineNumbers` создаёт по DOM-узлу на строку. Замер: мегабайт без нумерации занимает
+4 узла, с нумерацией — больше пятнадцати тысяч, и заметно блокируется основной поток. На
+файлах в тысячи строк нумерацию выключают, а слишком большой ввод потребитель
+обрезает сам: компонент — просмотрщик, а не редактор, и виртуализации у него
+нет.
+
+## Подсветка кита
+
+`highlightCodeNodes(code, language)` из входа `@olddevs/ui/editor/highlight`
+красит код той же грамматикой и той же темой, что блок кода в
+[Редакторе](../inputs/rich-text-editor.md) и [`RichTextView`](rich-text-view.md):
+GitHub Light в теме `light`, GitHub Dark в `dark` и `dim`. Тема следует
+ближайшему предку с `data-theme`, поэтому `CodeView` на вложенном светлом
+Листе (`surface="paper"`) внутри тёмного приложения светлый.
+
+```tsx
+// Серверный компонент: подсветка не попадает в клиентский бандл.
+import { CodeView } from "@olddevs/ui";
+import { highlightCodeNodes } from "@olddevs/ui/editor/highlight";
+
+export function Webhook({ body }: { body: string }) {
+  return (
+    <CodeView code={body} title="payload.yaml" copyable>
+      {highlightCodeNodes(body, "yaml")}
+    </CodeView>
+  );
+}
+```
+
+- **Языки** — те же, что у Редактора: Python, TypeScript, JavaScript, Go, HTML,
+  JSON, YAML, Markdown. Регистр и пробелы не важны, псевдонимы (`py`, `ts`, `js`,
+  `golang`, `htm`, `yml`, `md`) приводятся к имени. На неизвестном языке и на
+  пустом коде хелпер возвращает `null`: `children` пуст, и `CodeView` выводит код
+  как есть — с нумерацией строк, если она включена.
+- **Узлы, а не строка.** Код становится текстовыми узлами React, токены —
+  `span` с классами `hljs-…`; разметка из кода остаётся текстом. Хуков и
+  `"use client"` у хелпера нет: его можно вызывать и в серверном, и в
+  клиентском компоненте.
+- **Фон блока — у темы подсветки.** Цвета GitHub не держат 4,5:1 на подложке
+  кода кита, поэтому под токенами кита область кода берёт фон темы. Хелпер
+  ставит на корень токенов маркер `data-code-highlight`, и `CodeView` включает
+  фон только по нему: разметка своего подсветчика, даже с теми же классами
+  `hljs-…`, не перекрашивается.
+- **Нумерации строк с подсветкой нет** — по тому же правилу, что для любой
+  разметки (раздел ниже).
+- **Цена.** Сам `CodeView` и основной вход `@olddevs/ui` подсветчика не
+  импортируют. Lowlight, ядро highlight.js и восемь грамматик — 22,6 кБ gzip —
+  попадают в бандл только у того, кто импортировал `@olddevs/ui/editor/highlight`;
+  ставить для него нужно `lowlight` и `highlight.js` (пакеты движка
+  Редактора, в манифесте кита их нет).
+
+Почему хелпер, а не проп `language`: условного импорта не бывает, и проп держал
+бы подсветчик в графе основного входа у каждого потребителя кита. Граница —
+ADR-0039,
+сужена ADR-0052.
+
+Свой подсветчик (Shiki, Prism) по-прежнему кладётся в `children` — тему и фон
+тогда выбирает потребитель, кит их не трогает.
+
+## Почему `code` обязателен даже с разметкой
+
+Копирование берёт строку, а не DOM. Копирование из разметки утащило бы в буфер
+обмена номера строк и границы токенов подсветки — то есть текст, который не
+компилируется.
+
+По той же причине число строк считается по `code`: гутер, считающий себя по
+разметке, разъедется с содержимым на первом же подсветчике, который завернёт
+строку в два элемента.
+
+## Нумерация не работает ни с разметкой, ни с переносом
+
+С `children` гутер не рендерится вовсе, и это намеренно. Кит не знает, где в сторонней
+разметке границы строк: подсветчик волен завернуть строку во сколько угодно
+элементов. Номер напротив не той строки хуже, чем его
+отсутствие.
+
+С `wrap` — по той же причине, только источник расхождения другой: перенесённая
+строка занимает в тексте два и более ряда, а в колонке номеров по-прежнему один.
+Номер встаёт напротив не той строки, и последняя строка кода остаётся без номера
+вовсе.
+
+Завершающие переводы строки при подсчёте срезаются все: файл, прочитанный с
+диска, почти всегда кончается хотя бы одним, а бывает и двумя. Иначе каждый такой перевод давал
+бы лишний номер у пустой строки в конце.
+
+## Что кит всё-таки делает
+
+То, чего подсветчик не решает и что иначе каждый потребитель пишет заново:
+перенос или прокрутка вместо обрезки, нумерация строк, моноширинный шрифт из
+токена типографики и копирование готовой `CopyButton`.
+
+## Доступность и семантика
+
+- Номера строк `aria-hidden` и `select-none`: в речи они шум, потому что каждая строка начиналась бы с числа, а в буфере обмена — мусор. Колонка номеров липнет к левому краю: иначе при прокрутке вправо она уезжает за край ровно тогда, когда нужнее всего.
+- Область горизонтальной прокрутки фокусируема (`tabindex="0"`): до содержимого, которое прокручивается только указателем, клавиатура не доберётся — правило axe `scrollable-region-focusable`.
+- Цвета токенов у подсветки кита — тема GitHub, общая с Редактором; axe мерит контраст каждой роли токена во всех трёх темах (история `KitHighlighting` в `src/editor/CodeViewHighlighting.stories.tsx`). Разметку своего подсветчика кит не красит.
+- См. `src/components/content/CodeView.tsx`, `src/components/content/CodeView.stories.tsx`, `tests/code-view.test.tsx`; подсветка кита — `src/editor/features/code/highlightNodes.ts`, `src/editor/CodeViewHighlighting.stories.tsx`, `tests/code-view-highlight.test.tsx`.