# 🦷 React Advanced Odontogram
[](https://github.com/ZoliQua/React-Advanced-Odontogram/releases)
[](https://github.com/ZoliQua/React-Advanced-Odontogram)
[](https://www.npmjs.com/package/react-advanced-odontogram)
[](https://github.com/ZoliQua/React-Advanced-Odontogram/blob/main/LICENSE)
[](https://doi.org/10.5281/zenodo.21156787)
[](https://reactjs.org/)
[](https://www.typescriptlang.org/)
---
> 🌐 **Languages:** 🇬🇧 [English](README-en.md) | 🇪🇸 [Español](README-es.md) | 🇩🇪 [Deutsch](README-de.md) | 🇭🇺 [Magyar](README-hu.md) | 🇮🇹 [Italiano](README-it.md) | 🇸🇰 [Slovenčina](README-sk.md) | 🇵🇱 [Polski](README-pl.md) | 🇷🇺 [Русский](README-ru.md) | 🇧🇷 [Português (BR)](README-pt-br.md) | 🇸🇦 [العربية](README-ar.md) | 🇨🇳 [简体中文](README-zh.md) | 🇫🇷 [Français](README-fr.md)
---
## 📑 Содержание
- [📋 Обзор](#-обзор)
- [📦 Использование в качестве npm-пакета](#-использование-в-качестве-npm-пакета)
- [✨ Основные возможности](#-основные-возможности)
- [📦 Модули](#-модули)
- [🛠️ Элементы управления интерфейса](#-элементы-управления-интерфейса)
- [🦷 Типы зубов и состояния](#-типы-зубов-и-состояния)
- [⚙️ Настройки](#-настройки)
- [🖼️ Система SVG-шаблонов](#-система-svg-шаблонов)
- [🔢 Системы нумерации](#-системы-нумерации)
- [🚀 Использование](#-использование)
- [🔗 Интеграция](#-интеграция)
- [🧪 Тестирование](#-тестирование)
- [📖 Документация API](#-документация-api)
- [📡 Публичный API](#-публичный-api)
- [💾 Сохранение состояния (localStorage)](#-сохранение-состояния-localstorage)
- [💾 Формат экспорта/импорта статуса](#-формат-экспортаимпорта-статуса)
- [🖨️ Экспорт](#-экспорт)
- [📁 Структура папок](#-структура-папок)
- [⚙️ Технологический стек](#-технологический-стек)
- [📝 Примечания](#-примечания)
- [🔒 Примечания по безопасности](#-примечания-по-безопасности)
- [📖 Как цитировать](#-как-цитировать)
## 🇷🇺 Русский
### 📋 Обзор
Данный проект представляет собой интерактивный браузерный редактор одонтограммы, обеспечивающий быстрое заполнение зубной карты с удобным интерфейсом. Компонент отображает многослойные SVG-шаблоны зубов для представления реставраций, кариеса, эндодонтического статуса, подвижности и других клинических данных, а также поддерживает множественный выбор, фильтры выделения и предустановленные статусные шаблоны.
---
🔗 **Test URL:** https://react-advanced-odontogram.vercel.app/
---
### 📦 Использование в качестве npm-пакета
Одонтограмма поставляется как самодостаточная библиотека React-компонентов на npm:
[`react-advanced-odontogram`](https://www.npmjs.com/package/react-advanced-odontogram).
#### Требования
- **React 18 или 19** (объявлен как peer-зависимость — предоставляется вашим приложением).
- **Сборщик**, понимающий поле `exports` и ESM: Vite, webpack 5, Next.js, Rollup, esbuild, Parcel. Пакет **только ESM**.
- Node **≥ 18** для инструментария.
#### Установка
```bash
npm install react-advanced-odontogram react react-dom
```
#### Базовое использование
Отрисуйте `OdontogramShell` и импортируйте таблицу стилей **один раз** в любом месте вашего приложения:
```tsx
import { OdontogramShell } from "react-advanced-odontogram";
import "react-advanced-odontogram/style.css";
export function Chart() {
return (
);
}
```
#### Пропсы компонента
`OdontogramShell` — управляемый компонент. Наиболее часто используемые пропсы:
| Проп | Тип | По умолчанию | Описание |
|------|------|---------|-------------|
| `language` | `Language` | `"hu"` | Язык интерфейса (`hu`/`en`/`de`/`es`/`it`/`sk`/`pl`/`ru`/`pt-br`/`ar`/`zh`). |
| `numberingSystem` | `"FDI" \| "Universal" \| "Palmer"` | `"FDI"` | Система нумерации зубов. |
| `darkMode` | `boolean` | `false` | Переключатель тёмной темы. |
| `readOnly` | `boolean` | `false` | Отключить всё редактирование (только просмотр). |
| `themeConfig` | `OdontogramThemeConfig` | — | Переопределить CSS-переменные темы (`--odon-*`). |
| `plugins` | `OdontogramPlugin[]` | — | Зарегистрировать пользовательские плагины состояния / дополнительные слои. |
| `enableNotes` | `boolean` | `false` | Включить заметки по каждому зубу. |
| `enableIcdas` | `boolean` | `false` | Включить оценку кариеса по ICDAS II. |
| `fillingComplexity` | `"complex" \| "simple"` | `"complex"` | Сложность пломбы: `"simple"` (один материал на зуб) или `"complex"` (материалы по поверхностям). |
| `fillingDefectEnabled` | `boolean` | `true` | Включает фиксацию дефектов пломбы на карточке «Пломбы». |
| `fillingMaterialAvailability` | `Record` | все доступны | Доступные пломбировочные материалы в виде логической карты по `amalgam`/`composite`/`gic`/`temporary` (неизвестные ключи игнорируются). |
| `fissureSealingEnabled` | `boolean` | `true` | Включает герметизацию фиссур на карточке «Пломбы». |
| `screenToothSpacing` | `"wide" \| "normal" \| "close"` | `"normal"` | Расстояние между зубами на экране. |
| `screenToothNumberSize` | `"small" \| "normal" \| "xlarge"` | `"normal"` | Размер номера зуба в сетке. |
| `selectionColor` | `string` | `"#3b7bff"` | Цвет кольца выделения (`#rrggbb`). |
| `selectionBorderStyle` | `"solid" \| "dashed" \| "dotted"` | `"dashed"` | Стиль границы кольца выделения. |
| `toothInfo` | `boolean` | `true` | Показывать панель информации о зубе. |
| `onFillingComplexityChange` / `onFillingDefectEnabledChange` / `onFillingMaterialAvailabilityChange` / `onFissureSealingEnabledChange` | `(...) => void` | — | Срабатывает, когда пользователь меняет соответствующую настройку в Настройки → Пломбы. |
| `onLanguageChange` / `onNumberingChange` / `onDarkModeChange` | `(value) => void` | — | Срабатывает, когда пользователь меняет настройку через интерфейс. |
Также принимаются более тонкие пропсы уровня детализации (`pulpDetailLevel`, `secondaryCariesMode`, `rootCariesMode`, `radiographicDepthMode`, `wearDetailLevel`, `discolorationDetailLevel`, `surfaceNotation`, `showStatusCard`, `showOrthoCard`) — полный типизированный список см. в поставляемых типах `.d.ts`.
Четыре пропса заполнений выше предназначены **только для восстановления**: пропущенный пропс никогда не пишет в движок (императивный вызов `setFillingComplexity()` до монтирования сохраняется, автономный режим не меняется), а переданный пропс записывает движок и состояние модального окна «Настройки» вместе, поэтому окно никогда не показывает устаревшее значение. `fillingMaterialAvailability` применяется через diff по каноническому сериализованному ключу — повторный рендер с inline-литералом идентичного содержимого никогда не перезаписывает движок. Соответствующие колбэки `on*Change` вызываются из Настройки → Пломбы: это путь обратной записи для хостов, сохраняющих предпочтения.
#### Публичный API (именованные экспорты)
`OdontogramShell` является одновременно экспортом по умолчанию и именованным экспортом. Императивный API состояния, самостоятельный компонент `PerioChart`, направляемый тур и все публичные типы являются именованными экспортами из той же точки входа:
```ts
import {
OdontogramShell, // также экспорт по умолчанию
PerioChart, // самостоятельный компонент пародонтальной карты
// чтение состояния
getOdontogramSummary,
getToothStateSummary,
onStateChange, // подписка на изменения состояния
// экспорт / импорт
exportFhir, // пакет HL7 FHIR R4
exportSvg, exportImage, // векторный / растровый экспорт карты
setImportFormat,
// управление
setReadOnly, getReadOnly,
clearSelection, getSelectedTeeth,
registerPlugins, setPluginState, getPluginState,
startIntroTour, // запустить обучающий тур
// …и многие другие функции настроек setX/getX
} from "react-advanced-odontogram";
```
Полная поверхность API (≈ 44 функции + типы, такие как `OdontogramSummary`, `OdontogramThemeConfig`, `OdontogramPlugin`, `FhirExportOptions`, `PerioViewMode`, …) полностью типизирована во встроенных объявлениях.
#### Компонуемые поверхности (продвинутый уровень)
`OdontogramShell` — это поддерживаемый компонент «всё в одном», не требующий дополнительной настройки. Если вам нужно разместить области одонтограммы в разных частях собственной вёрстки, четыре поверхности интерфейса оболочки также экспортируются и могут быть скомпонованы под одним `OdontogramProvider`, при этом все они используют один сеанс, управляемый пакетом:
```tsx
import {
OdontogramProvider,
OdontogramTopbar,
OdontogramChartSurface,
ToothInfoSurface,
ToothControlsSurface,
} from "react-advanced-odontogram";
import "react-advanced-odontogram/style.css";
function Workspace() {
return (
);
}
```
`OdontogramProvider` принимает те же пропсы, что и `OdontogramShell`. Для создания собственных поверхностей доступны хук `useOdontogramUi()` (и тип `OdontogramUiContextValue`). Текущее ограничение: используйте один провайдер на страницу. Поверхности можно монтировать и размонтировать по мере необходимости — при повторном монтировании они автоматически перепривязываются. Сам `OdontogramShell` не изменился — это именно такая композиция в компоновке по умолчанию.
Для ещё более тонкой композиции также экспортируются отдельные карточки управления — `OrthodonticsCard`, `StatusesCard`, `CariesCard`, `FillingsCard`, `RootPeriodontiumCard` и `ToothDetailsCard` — каждая представляет собой самостоятельный декларативный компонент, который читает и записывает общий сеанс через API движка (для создания собственных экспортируется хук `useEngineState()`). Монтируйте только те карточки, которые нужны конкретной компоновке, в любом порядке, под одним `OdontogramProvider`.
#### Использование с Next.js (App Router)
Компонент работает только на клиенте, поэтому отрисовывайте его из клиентского компонента:
```tsx
"use client";
import { OdontogramShell } from "react-advanced-odontogram";
import "react-advanced-odontogram/style.css";
export default function OdontogramClient() {
return ;
}
```
Либо загружайте его через клиентский динамический импорт: `dynamic(() => import("./OdontogramClient"), { ssr: false })`.
#### Важные замечания и текущие ограничения
- **Только ESM** — пакет публикует единый ES-модуль (`dist/odontogram.js`) плюс точку входа для деклараций типов (`dist/index.d.ts`). Он ориентирован на разрешение модулей сборщиком; сборки CommonJS нет.
- **Таблица стилей отдельная** — вы **обязаны** импортировать `react-advanced-odontogram/style.css` один раз; она не подключается автоматически. Стилизация — это глобальный CSS, ограниченный областью `.odontogram-root` и управляемый CSS-переменными `--odon-*`.
- **SSR / только клиент** — компонент обращается к DOM при монтировании (`document`), поэтому он должен выполняться в браузере. В SSR-фреймворках отрисовывайте его в клиентском компоненте (`"use client"`) или через клиентский динамический импорт.
- **Ресурсы самодостаточны** — SVG зубов и иконок встраиваются в JavaScript-бандл на этапе сборки; **не требуется** загрузка ресурсов во время выполнения и нечего дополнительно копировать в вашу публичную папку.
- **Один экземпляр на страницу** — состояние движка в настоящее время является одиночным объектом на уровне модуля, поэтому отрисовка двух экземпляров `` на одной странице приведёт к тому, что они будут использовать общее состояние одной карты. Поддержка нескольких экземпляров запланирована на будущий релиз.
---
### ✨ Основные возможности
- 🖱️ Быстрый выбор и множественный выбор (CMD/CTRL + клик)
- 🦷 Типы зубов: постоянные, молочные, имплантаты, поддесневые, отсутствующие
- 🦷 Субстрат зуба (независимо от вида реставрации): натуральный, radix (корневой остаток), сломанный, подготовлен под коронку
- 👑 Реставрации по типу × материалу: коронка / вкладка (inlay) / накладка (onlay) / винир / мост из e.max, золота, gradia, циркония, металла, металлокерамики, телескопической конструкции или временной (накладка доступна только в окклюзионном виде) — выбираются из единого комбинированного селектора «Fix: Коронка – …» с минимумом кликов; устаревшие коронки `metal` автоматически мигрируют в `metal-ceramic` (металлокерамика); имплантаты используют ту же модель тип × материал, дополненную слоем имплантационного коннектора. Селектор ограничен видом зуба: имплантат предлагает только коронку/мост (плюс пять вариантов аттачментов, см. ниже); отсутствующий зуб/дефект предлагает только тело моста (плюс съёмный частичный/полный протез); субстрат `radix` полностью скрывает элемент управления реставрацией (на корневом остатке реставрация не может быть назначена)
- 🦿 Съёмное/аттачментное протезирование на отдельной оси `prosthesis` (записи «Kivehető:» в комбинированном селекторе): формирователь десны имплантата, локатор, локатор с покрывным протезом, балка, балка с покрывным протезом; съёмный частичный или полный протез с опорой на зубы
- 🌉 Зубы моста отображают одновременно коронковую часть и седловидный коннектор; оверлей многозубого мостовидного пролёта отрисовывает единый непрерывный, учитывающий дугу коннектор через последовательные зубы моста (тело + опоры) и межзубные промежутки между ними (верхняя и нижняя дуга используют зеркальную геометрию седла, сохраняя выравнивание коннектора на обеих дугах), включён в экспорт PNG/JPG/SVG; применение моста через шаблон статусов немедленно пересчитывает оверлей
- 🔍 Картирование кариеса на 6 поверхностях: мезиальная, дистальная, щёчная, язычная, окклюзионная, подкоронковая
- 🪥 Материалы пломб по поверхностям: амальгама, композит, стеклоиономер (СИЦ), временная
- 🏥 Единый объединённый селектор «Статус пульпы / эндо» (сгруппирован: витальная пульпа vs. леченная/эндо): эндодонтические состояния (лечебное пломбирование, пломбирование канала, неполное пломбирование канала, стекловолоконный штифт, металлический штифт) и диагноз пульпы по AAE (`pulpDx`: норма / обратимый / необратимый пульпит / некроз) взаимоисключающие — зуб с эндодонтическим лечением (установлен `endo`) не может одновременно нести диагноз витальной пульпы; при лечении `pulpDx` нормализуется к `normal`, а глиф поражённой пульпы скрывается. Обратимый пульпит отображается уменьшенным глифом пульпы. Опциональная 3-уровневая настройка детализации пульпы (`pulpDetailLevel`: simple / AAE / практический латинский) раскрывает 9 практических латинских подтипов пульпы (pulpa sana … gangraena pulpae) через `pulpLatin`; резекция и парапульпарный штифт остаются отдельными специальными индикаторами
- 🦴 Апикальный диагноз (`apicalDx`: симптоматический/бессимптомный апикальный периодонтит, острый/хронический апикальный абсцесс, конденсирующий остеит) напрямую определяет периапикальный глиф; уточняющий подтип очага гранулёма/киста отображается только при симптоматическом/бессимптомном апикальном периодонтите (избыточный подтип «абсцесс» убран — он уже покрывается апикальным диагнозом)
- 🩹 Объединённая карточка «Корень и пародонт» (единый сворачиваемый раздел для находок корня/периапикальной области и пародонта)
- ⚕️ Модификации: периапикальное воспаление (отображается только на отсутствующих зубах/лунках после удаления; скрыто на присутствующих зубах, где периапикальный глиф определяется исключительно `apicalDx`, и на имплантатах, где это покрывает `periImplant`), заболевание пародонта, степени подвижности (M1/M2/M3, скрыты на имплантатах)
- 🦷🔩 Статус периимплантных тканей (`periImplant`: `none` / `mucositis` / `peri-implantitis-mild` / `peri-implantitis-moderate` / `peri-implantitis-severe`) — стадирование по классификации Всемирного семинара 2018 года, отображается как отдельный селектор на имплантатах; мукозит использует глиф пародонтальной десны, периимплантит добавляет градуированный слой `peri-implant-bone-loss` (непрозрачность 0,4/0,7/1,0). Имплантаты больше не отображают глиф периапикального очага — их воспаление выражается через эту ось — а флажки пародонтальных модификаторов скрыты на имплантатах (специальное переименование флажка «Периимплантит» упразднено)
- 🏷️ Специальные индикаторы: требуется коронка, требуется замена коронки, закрытый дефект после удаления, планируемое удаление, герметизация фиссур, потеря контактного пункта
- 👁️ Переключение видимости: окклюзионный вид, зубы мудрости, кость и пульпа
- 🔢 12 фильтров выбора (все, присутствующие, постоянные, молочные, имплантаты, отсутствующие, верхние/нижние, фронтальные/моляры)
- 📊 Предустановленные статусные шаблоны (сброс, молочный прикус, сменный прикус, беззубый)
- 📦 34 предустановленных шаблона реставраций (мосты, съёмные протезы, балочные протезы с имплантатами)
- 💾 Экспорт/импорт статуса в JSON (версия 2.22; импорт по-прежнему принимает устаревшие версии 1.4 и 2.0–2.21 и автоматически мигрирует их, с пользовательскими состояниями плагинов и заметками к зубам)
- 💽 Опциональное сохранение состояния в localStorage (`enablePersistence`/`disablePersistence`/`clearPersistedState`/`isPersistenceEnabled`) — по умолчанию отключено; автоматически сохраняет статусную карту (и, опционально, карту плана) при каждом изменении состояния и восстанавливает её при следующем монтировании компонента, с ограничением размера 4 МБ и передачей ошибок хранения/парсинга в колбэк `onError` (или `console.warn`) вместо выброса исключения
- 🔗 Экспорт HL7 FHIR R4 (коллекция Bundle наблюдений по каждому зубу, кодирование зубов ISO 3950 для постоянного прикуса **и** молочных зубов (51–85, без потерь при обратном импорте), локальная система кодов, а также опциональный слой SNOMED CT (Настройки → SNOMED CT)); компонент кариеса с заданной тяжестью также несёт кодировку системы оценки — ICDAS на первичной (без пломбы) поверхности, CARS на рецидивирующей (с пломбой) С DX-11 вместе с ним передаётся и ПЛАН: каждое запланированное вмешательство становится `ServiceRequest` (`intent: "plan"`) с кодом намеченного клинического состояния зуба.
- ✚ Интерфейс выбора поверхностей «крест/плюс» (B/M/O/D/L) для кариеса и пломб
- 🧱 Материалы реставраций по поверхностям (смешанные пломбы, например щёчная амальгама + дистальный композит)
- 🖼️ Экспорт зубной карты в PNG/JPG/SVG (для загрузки; PNG/JPG растеризованы из векторного SVG)
- 🦷 Кариес/вторичный кариес как конечный автомат состояний по поверхностям: кариозная поверхность без пломбы отображается как первичный кариес (непрозрачность по уровням ICDAS); как только на этой поверхности появляется пломба, она отображается как вторичный (рецидивирующий) кариес (слой `subcaries-{surface}`, с оценкой CARS) — оба состояния никогда не активны одновременно на одной поверхности
- 🎯 Единая оценка тяжести по поверхности (`cariesSeverity`, 0–6, заменяет прежние отдельные поля глубины ICDAS и CARS): читается как глубина ICDAS на первичной поверхности, как именованная оценка CARS (Здоровый … Обширная полость) на рецидивирующей, через контекстное всплывающее окно, показывающее только шкалу, соответствующую текущему состоянию поверхности
- 🌱 Кариес корня (`rootCaries`: none / active / arrested / active-cavitated), задействующий отдельный слой изображения кариеса корня с непрозрачностью, зависящей от тяжести (active 0,5 / arrested 0,7 / active-cavitated полная непрозрачность)
- 📡 Рентгенологическая глубина кариеса (`radiographicDepth`: none / E1 / E2 / D1 / D2 / D3 по поверхности), независимая от визуальной шкалы тяжести ICDAS/CARS, отображается в виде значка и передаётся через собственное наблюдение FHIR
- 🎚️ Три настройки детализации кариеса (`secondaryCariesMode`, `rootCariesMode`, `radiographicDepthMode`) и переключатель `cariesDepthEnabled`, сворачивающие каждую шкалу в более простой вид выбора без потери сохранённого значения
- 🩹 Строка сводки по вторичному кариесу на панели пломб: под элементами управления пломбами перечисляет каждый выбранный зуб со вторичным кариесом и его поверхности (например, «На пломбе зуба 36 (O) обнаружен вторичный кариес.»)
- 🪛 Дефекты пломб по поверхностям (`fillingDefect`: none / marginal / fracture / wear) на прямых реставрациях, независимо от вторичного кариеса — задаются через индикатор по поверхностям на карточке пломб (по аналогии с индикатором глубины кариеса, список опций расположен вертикально), отображаются на карте, во всплывающей подсказке и в общей сводке пломб по всей полости рта с явной меткой (например, «36 (O) – Дефект пломбы: O: краевой»), так же как маркируется вторичный кариес в строке кариеса; карточка пломб также показывает подсказку для любого выбранного зуба с зарегистрированным дефектом пломбы (например, «У зуба 36 зарегистрирован дефект пломбы.»), аналогично существующей подсказке о вторичном кариесе
- 🦷💥 Стирание зубов, типизированное по клинической причине и локализации (`wearEdge`: none / attrition (истирание) / erosion (эрозия), режущий край/окклюзионная поверхность; `wearCervical`: none / abrasion (абразия) / abfraction (абфракция) / erosion (эрозия), пришеечная область) — заменяет два бинарных флага стирания при бруксизме; задаётся через два выпадающих списка в строке стирания, использует существующую графику стирания и отображается во всплывающей подсказке и в новом сводном разделе «Стирание» по всей полости рта
- 🎨 Изменение цвета зуба по причине (`discoloration`: none / tetracycline (тетрациклиновое) / fluorosis (флюороз) / nonvital (депульпированный) / extrinsic (внешнее) / other (другое)) на постоянных и молочных зубах — придаёт отображаемой натуральной коронке репрезентативный оттенок, когда зуб не имеет реставрации и натуральный субстрат; отображается во всплывающей подсказке и в новом сводном разделе «Изменение цвета» по всей полости рта; дополняет набор поверхностных и структурных состояний наряду с дефектами пломб и стиранием
- ✏️ Передние зубы (резцы/клыки) обозначают свою жевательную поверхность как «режущая» (incisal) во всём интерфейсе (выбор, всплывающее окно, сводки); сохранённый ключ поверхности остаётся `occlusal`
- 🔤 Позиционно-зависимая нотация поверхностей (Настройки → Детали зуба → «Нотация поверхностей», simple/full, по умолчанию full): в полном режиме буква и метка поверхности кариеса/пломбы следуют анатомии зуба — occlusal → I/incisal (режущая) на передних зубах, buccal → L/labial (губная) на передних зубах, lingual → P/palatal (нёбная) на верхних зубах и L/lingual (язычная) на нижних зубах (mesial/distal/subcrown не затрагиваются); упрощённый режим всегда использует общий набор B/M/O/D/L/SC независимо от положения зуба. Применяется к сводке по всей полости рта и к обоим селекторам поверхностей (кариес и дефект пломбы) (буква + подпись); сохранённый ключ поверхности не затрагивается
- 🦷↕️ Ортодонтическое картирование по зубам (`orthoAppliance`: none / bracket (брекет) / band (кольцо); `orthoDrift`: none / mesial (мезиальный) / distal (дистальный); `orthoVertical`: none / extrusion (экструзия) / intrusion (интрузия); `orthoRotation`: логическое значение) на присутствующем натуральном зубе (постоянном или молочном) — использует ранее не задействованную графику ортодонтии версии 2.5.0 (без новых SVG); отображается на карте, во всплывающей подсказке и в новом сводном разделе «Ортодонтия» по всей полости рта
- 🪨 Зубной камень, а также резорбция корня, типизируемая как внутренняя или наружная цервикальная (`resorptionType`)
- 📏 Глубина кариеса по поверхностям (поверхностный / дентин / глубокий), или опциональная оценка по ICDAS II (0–6) через `enableIcdas`
- 🩹 Переключатель краевой негерметичности коронки, отображается только при реставрации коронкой или мостом
- 🧬 Кодирование диагнозов по стандарту (WHO ICD-10, всегда включено): каждая зафиксированная находка формирует диагноз, закодированный по ICD-10 — кариес зубов (K02), кариес корня и приостановившийся кариес (K02.2/.3), пульпит и некроз пульпы (K04.0/.1), апикальный периодонтит, периапикальный абсцесс и радикулярная киста (K04.4–.9), стирание/абразия/эрозия/абфракция (K03.0–.8), зубной камень (K03.6), резорбция зуба (K03.3), изменение цвета зуба (K00.3/K00.8/K03.7), потеря зуба (K08.1), корневой остаток (K08.3) и перелом зуба (S02.5) — отображается во всплывающей подсказке и сводке по всей полости рта, экспортируется как ресурсы FHIR Condition.
- 🩺 Карточка «Диагнозы» по зубу: просматривайте выведенные ICD-10-диагнозы зуба и редактируйте их — подавите ошибочно выведенный диагноз или добавьте тот, который на карте не отражён. Итоговый набор (выведенные − подавленные + добавленные) определяет экспорт FHIR.
- 🗺️ Состояния случая / регионарные: фиксируйте диагнозы для всей полости рта, не привязанные к одному зубу — аномалия прикуса и болезни височно-нижнечелюстного сустава (K07), кисты полости рта (K09), болезни слюнных желёз (K11), стоматит и поражения слизистой оболочки рта (K12/K13), а также аномалии развития зубного ряда на уровне дуги (K00) — каждый диагноз можно опционально указать со стороной поражения (слева / справа / двусторонне).
- 🌍 Национальные пакеты кодирования (Настройки → Система кодирования диагнозов): накладывает национальную систему кодов поверх базы WHO ICD-10 — BNO-10 (венгерская, локализованное отображение; сохраняет код WHO) или US ICD-10-CM (перекодированные коды, например диапазон K07 для дентофациальных аномалий → M26). Добавление пакета для другой страны — это небольшая запись `CodingPack` — см. `CODING_PACKS.md`.
- 🔬 Слой SNOMED CT (Настройки → SNOMED CT, опционально, по умолчанию выключено): добавляет кодирование SNOMED CT наряду с кодом WHO и любым национальным пакетом, а также кодирует периимплантные находки, для которых нет кода WHO ICD-10. Коды ICD-10-CM и идентификаторы понятий SNOMED являются справочными/ориентировочными — перед клиническим использованием проверьте их по официальному табличному перечню ICD-10-CM / браузеру SNOMED CT.
- 🔁 Двусторонний обмен FHIR Condition: диагнозы экспортируются как ресурсы FHIR `Condition` (привязанные к зубу, а также состояния на уровне пациента с полем `bodySite` для указания стороны поражения) наряду с Observation, а импорт восстанавливает их — состояния случая напрямую, а переопределения добавления/подавления по зубам — путём сравнения (diff) импортированных Condition с заново выведенной картой.
- 🩺 **Карточка диагнозов, обновлена:** в каждой строке диагноза по зубу сначала показан код ICD-10 (`K04.0 Pulpitis`), строки отсортированы по коду. У каждой строки есть переключатель **исключить** (убирает диагноз из экспорта FHIR, но оставляет его на карте) и кнопка **удалить** (×), которая убирает диагноз *и* соответствующую находку на зубе. Добавление диагноза из выбора записывает и лежащую в основе находку на карте, поэтому значок появляется сразу.
- 🗂️ **Всплывающее окно диагнозов случая/региональных диагнозов:** диагнозы для всей полости рта и региональные диагнозы (аномалии челюсти, кисты, заболевания слюнных желёз и слизистой…) перенесены из боковой панели пародонта в отдельный диалог, открываемый кнопкой **Диагнозы** рядом с переключателем Одонтограмма / Пародонтальный статус; выбор в нём отсортирован по коду, код указывается первым.
- 🇭🇺 **Пакет BNO-10:** отображаемые венгерские названия теперь являются официальными наименованиями BNO-10 (NEAK), а пакет использует стандартный URI системы ICD-10 (BNO-X идентичен ICD-10 ВОЗ).
- ✅ **Экспорт FHIR, чистый для валидаторов HL7:** каждая запись Bundle несёт детерминированный `id` и абсолютный `fullUrl` (без заполнителей `urn:uuid`), а Bundle включает в себя собственную **CodeSystem** движка, чтобы его локальные коды разрешались при валидации; та же CodeSystem опубликована в репозитории как `fhir/CodeSystem-odontogram.json` (передайте `includeCodeSystem: false` в опциях экспорта FHIR, чтобы её опустить).
- 🎯 **Коды ICD, следующие за картой (специфичность на основе данных).** Глубина кариеса берётся из рентгенологической глубины, если она зафиксирована (E1/E2 → эмаль, D1–D3 → дентин), а иначе — из тяжести по ICDAS как запасного варианта (1–3 → эмаль, 4–6 → дентин); это уточняет код ВОЗ `K02` до `K02.0` / `K02.1`, а код ICD-10-CM `K02.9` — до `K02.51/.52` (ямки и фиссуры) или `K02.61/.62` (гладкая поверхность) в зависимости от поверхности × глубины. Хронический пародонтит получает свой код ICD-10-CM из стадии и распространённости 2017 года (`K05.311`–`K05.329`). Одна Condition на зуб, с самым глубоким поражением.
- 🔄 **Пародонтальные данные теперь возвращаются и через FHIR.** Импорт считывает пародонтальные панели LOINC 74029-0 обратно в каждый зуб — глубину зондирования, десневой край (восстановленный из CAL, поэтому значения псевдокармана сохраняются), BOP, фуркацию, налёт по O'Leary, индексы PI/GI и имплантатные mPI/mBI, а также ширину кератинизированной десны — плюс доказательные Observation по статусу курения и HbA1c. Также распознаются Condition, закодированные только в ICD-10-CM или SNOMED CT, так что чужой bundle импортирует всё, что может.
- 🧬 **SNOMED CT для всего каталога диагнозов.** 48 из 50 позиций теперь несут проверенное понятие SNOMED CT International (активное, в основном модуле, с соответствующим FSN). Два остаются намеренно незаполненными, поскольку у SNOMED International нет для них обобщающего понятия: аномалия размера челюсти (K07.0) и дентофациальные функциональные нарушения (K07.5). Наложение SNOMED остаётся опциональным в настройках.
- 📦 **Загружаемый пакет терминологии FHIR.** Папка `fhir/` в репозитории — это FHIR NPM-пакет (`react-advanced-odontogram.fhir`, FHIR 4.0.1), содержащий CodeSystem движка и сгенерированные ValueSet — по одному на каждую группу значений клинической оси, один для типов находок и один сводный набор всех кодов. Направьте на него валидатор через `-ig ./fhir`.
- 🧰 Унифицированная панель иконок в верхней части с вкладками в модальном окне настроек (Общие / Панели / Детали зуба / Кариес / Пульпа / Заметки / Периодонтальный — нумерация, заметки, видимость панелей, ICDAS, переключатель глубины кариеса, детализация кариеса корня/рентгенологической глубины, уровень детализации пульпы, уровень детализации стирания/изменения цвета зубов, информация о зубах)
- 🗂️ Вкладка настроек «Панели»: независимое отображение/скрытие сводных панелей «Статусы» и «Ортодонтия» по всей полости рта
- 🦷🩺 Вкладка настроек «Периодонтальный»: 16 переключателей показать/скрыть для каждого индекса строк пародонтальной карты (сгруппированы по карманам/гигиене/мукогингивальным параметрам/поддержке/периимплантным индексам — PD/GM/CAL/BOP, зубной налёт, PI, GI, видимость CEJ, вогнутость корня, KG, GT, фуркация, подвижность, класс Миллера, mPI, mBI), каждый с описанием, плюс режим отображения названия индекса переведённое/каноническое (каноническое = фиксированное научное название на английском/латыни на любом языке интерфейса; всплывающие подсказки всегда остаются локализованными независимо от этой настройки). Обе настройки — предпочтения на уровне приложения (как `perioViewMode`) — никогда не входят в экспортируемый payload
- 🩹 Настройки вторичного кариеса (CARS) объединены с вкладкой настроек кариеса, размещены над рентгенологической глубиной (отдельная вкладка «Вторичный кариес» упразднена)
- 🎚️ Уровень детализации в разделе «Детали зуба» (Настройки → Детали зуба): настройка simple/complex для стирания зубов и для изменения цвета. Упрощённый режим показывает переключатель да/нет для каждой находки (стирание вкл. → attrition/abrasion, изменение цвета вкл. → other); сложный режим (по умолчанию) сохраняет выпадающие списки типа/причины, при этом сохранённое значение сохраняется при переключении уровней
- 📋 Панель информации о зубах: текстовое сводное описание всей одонтограммы в реальном времени (количество зубов, списки присутствующих/отсутствующих, кариес вкл. вторичный, пломбы, каналы, протетика, имплантаты, состояние пародонта) — отображается по умолчанию, переключается в настройках
- 🗂️ Сводное выпадающее меню экспорта (Статус JSON / FHIR / PNG / JPG)
- 📥 Выпадающее меню импорта с поддержкой FHIR (загружает ранее экспортированные Bundle)
- ⏳ Индикатор прогресса при экспорте изображения
- 🎓 Интерактивное обучение из 18 шагов
- 🔢 Три системы нумерации (FDI, Universal, Palmer)
- 🌐 Интернационализация — 12 языков интерфейса (HU/EN/DE/ES/IT/SK/PL/RU/PT-BR/AR/ZH/FR) с переключателем языков; арабский отображает интерфейс справа налево, а зубные/пародонтологические карты закреплены слева направо (машинный перевод, проверка носителем языка для AR/ZH/FR ожидается); в основной бандл входит только английский — каждый другой язык — отдельный чанк, загружаемый при первом выборе
- 🌗 Поддержка тёмного режима с кнопкой переключения (автономный или управляемый родительским приложением)
- 🎨 Настраиваемая тема (`themeConfig` prop) с CSS-переменными (`--odon-*`)
- 📱 Мобильный сенсорный интерфейс: всплывающее окно по касанию для масштабирования, контекстное меню по долгому нажатию, масштабирование жестом «щипок», сенсорные цели WCAG 44 пикселя, переключение зубной дуги
- 🔌 Система пользовательских плагинов SVG: визуальные наложения, пользовательское состояние каждого зуба, поддержка экспорта/импорта JSON — вывод `renderSvg()` плагина санитизируется библиотекой DOMPurify (SVG-профиль) перед вставкой в живую карту; плагины по-прежнему выполняются как доверенный код, поэтому загружайте плагины только из источников, которым вы доверяете
- 🛡️ Content-Security-Policy: production-сборка демо-приложения внедряет CSP-мета-тег (dev-сервер не затрагивается) — приложения-хосты, встраивающие компонент, должны задавать собственную CSP
- ⚠️ Предупреждения о несовместимых комбинациях состояний зуба
- 🏷️ Автоматические подсказки о состоянии на ячейках зубов (отображают все активные состояния)
- 🩺 Модернизированная всплывающая подсказка по зубу и сводная панель по всей полости рта: обе отображают полный набор клинических находок (диагноз пульпы/апикальный + подтип очага, резорбция корня, статус периимплантных тканей, градуированный кариес корня, зубной камень, краевая негерметичность коронки, перелом, потеря контакта, типизированное стирание края/пришеечной области), с отдельным разделом «Диагнозы» на панели, отдельным разделом «Стирание», а также приблизительным качественным показателем тяжести кариеса (поверхностный/умеренный/глубокий)
- ♿ Клавиатурная доступность (WCAG): роли ARIA listbox/option, выбор клавишами Enter/Пробел, навигация клавишами-стрелками, видимые контуры фокуса
- 🔒 Режим «только чтение»: отключение всех взаимодействий для печати, отчётов или просмотра
- ✨ Анимация выбора: пульсирующая пунктирная рамка и светящаяся тень на выбранных зубах (с поддержкой prefers-reduced-motion)
- 📝 Заметки к зубам: двойной щелчок для добавления/редактирования, значок заметки рядом с номером зуба, всплывающая подсказка с текстом заметки, строка «Индивидуальные заметки» в сводной панели по всей полости рта, включение в PDF-отчёт, экспорт/импорт в JSON
- 🔀 Разделение карты «Статус ↔ План»: переключатель `Статус | План` в заголовке карты переключает между текущей картой **статуса** и картой **плана** (предполагаемое лечение), каждая со своими состояниями зубов; карта плана при первом переключении на неё начинается как копия статуса, и изменения в одной карте никогда не влияют на другую. Экспорт/импорт (`exportStatus`/`exportFhir`/импорт файла) всегда относятся к карте статуса; карта плана читается/записывается отдельно через собственный API (см. Публичный API ниже) и — если она отличается от статуса — включается в экспорт JSON как дополнительный раздел `plan`
- 📝 Блок «Что изменится»: если план отличается от текущего статуса, блок под панелью информации о зубах перечисляет каждое различие по зубу и по оси лечения (наличие, субстрат, реставрация, протезирование, планируемая коронка, ортодонтия, пульпа/эндо, апикальный статус) в виде строки `зуб: ось из → в`; также доступен программно через `getPlanChanges()`
- 🩺 Пародонтологическое картирование: **глубина зондирования (PD)**, **десневой край (GM)**, **кровоточивость при зондировании (BOP)** (+ суппурация) по каждой из шести стандартных точек на зуб, с производным **уровнем клинического прикрепления (CAL = PD + десневой край)**, рецессией и общим показателем **%BOP** по всей полости рта. **Графическая пародонтальная карта на всю полость рта** — каждая дуга отрисовывается как **два отдельных SVG — щёчный и нёбный/язычный** (переиспользуют графику зуба с единой ориентацией «коронки к центральной полосе» на обеих сторонах; отдельная **графика имплантата** для зубов-имплантатов) с красной **линией CEJ**, **пронумерованной миллиметровой координатной сеткой** и **кривой десневого края / глубины кармана** над зубами, разделённой **центральной полосой пародонтальных индексов** (с подписью `▲ Buccal … Lingual/Palatal ▼`), несущей общие для обеих сторон индексы по зубу — **класс Миллера** в самом верху, а **зубной налёт/PI/GI/mPI/mBI** отображаются как **анатомическая ромбовидная плитка** на зуб (щёчная вершина вверх, язычная — вниз, мезиальная/дистальная стороны в среднем ряду меняются местами в зависимости от стороны, так что мезиальная сторона всегда направлена к средней линии дуги); числовые строки (полные названия индексов — PD/GM/CAL/BOP + подвижность + фуркация — в более крупных, удобных для касания ячейках) выровнены по столбцам, плюс сводка (средние PD/CAL, %BOP, PI%), с вводом через **автоматический переход по клавиатуре**; карта **динамически масштабируется, заполняя доступную ширину**, адаптивна при любом размере окна. Представлена как **переключатель вида** «Одонтограмма | Пародонтальный статус», правая панель которого при активном виде переоформляется в **боковую панель пародонтального контекста** (данные пациента, классификация 2017 года и сводка по всей полости рта) (опция в настройках переключает всё представление обратно во **всплывающее окно**), а также остаётся **отдельно вызываемым компонентом** (экспорт `PerioChart`), так что принимающее приложение может вызывать пародонтальную карту независимо от базовой одонтограммы. Экспорт **FHIR** по каждой точке через пародонтальную панель LOINC (`74029-0`; PD `32910-2`, рецессия `32911-0`, CAL `32912-8`)
- 🅿️ Предлагаемое оформление: в режиме «План» находки, которые план **добавляет** по сравнению с текущим статусом (планируемая коронка, удаление, ортодонтическое перемещение, протез, …), отображаются отдельным **пунктирным, тонированным контуром «предлагается»**, чтобы план читался как намерение, а не как факт — с легендой «пунктир = предлагается» на карточке карты. Отображение в режиме «Статус» побайтово идентично; лечение существует только в плане и полностью сбрасывается при переключении обратно
- 🚦 Ограничение режима «План»: карта «План» показывает только то, что стоматолог может *сделать* — базовый выбор предлагает только «Отсутствует» / «Постоянный» / «Имплант», а находки, относящиеся только к статусу (кариес, стирание зубов, изменение цвета, а также весь пародонтальный блок — подвижность, сетка зондирования по шести точкам, модификаторы воспаления/пародонта, зубной камень, статус периимплантных тканей), скрыты; элемент управления пульпой/эндодонтией сохраняет эндодонтическое **лечение** (пломбирование корневого канала / штифт / апикоэктомия / парапульпарный штифт), но скрывает **диагноз** пульпы/апикальной области и резорбцию корня. Реставрация, протезирование, ортодонтия, необходимость/замена коронки и план удаления остаются доступными для планирования
- 🧪 Обширный набор автоматических тестов Vitest: нумерация, переводы, шаблоны, i18n, компонент App, тема, сенсорный ввод, плагины, доступность и паритет клинических/диагностических осей
- 📖 Документация API TypeDoc с JSDoc-комментариями ко всем публичным экспортам (`npm run docs`)
### 📦 Модули
- 🦷 Сетка одонтограммы и интерфейс ячеек зубов
- 🎛️ Панель управления и статуса
- 🎨 Движок слоёв SVG и шаблоны
- 🔢 Нумерация зубов и сопоставление меток (FDI/Universal/Palmer)
- 🌐 Локализация — 12 языков интерфейса (HU/EN/DE/ES/IT/SK/PL/RU/PT-BR/AR/ZH/FR), включая арабский (RTL)
- 💾 Экспорт/импорт статуса
- 📋 Дополнительные статусы: предустановленные шаблоны реставраций
- 🎨 Настройка темы: настраиваемая цветовая палитра через CSS-свойства `--odon-*`
- 📱 Мобильные сенсорные взаимодействия (масштабирование по касанию, долгое нажатие, масштабирование жестом «щипок», переключение дуги)
- 🔌 Система пользовательских плагинов SVG
- ⚠️ Система валидации состояний и подсказок
- ♿ Клавиатурная доступность и поддержка ARIA
- 🔒 Режим «только чтение»
- ✨ Анимация выбора
- 📝 Система заметок к зубам
- 🧪 Набор автоматизированных тестов (Vitest + Testing Library)
### 🛠️ Элементы управления интерфейса
**🔝 Верхняя панель:**
- Переключатель языков (выпадающий список HU/EN/DE/ES/IT/SK/PL/RU/PT-BR/AR/ZH/FR)
- Кнопка переключения тёмного режима (иконка солнца/луны, переключает между светлой и тёмной темой)
- Переключатель системы нумерации (выпадающий список FDI/Universal/Palmer)
- Кнопки «Экспорт статуса» / «Импорт статуса»
**📊 Заголовок карты:**
- Переключатель окклюзионного вида
- Переключатель видимости зубов мудрости
- Переключатель видимости кости
- Переключатель видимости пульпы
- Кнопка сброса выделения
**🔍 Фильтры выбора:**
- Все / Все присутствующие / Постоянные / Молочные / Имплантаты / Все отсутствующие
- Верхние / Верхние 6 фронтальных / Верхние моляры
- Нижние / Нижние 6 фронтальных / Нижние моляры
**📋 Статусные шаблоны:**
- Сбросить всё (сброс полости рта)
- Молочный прикус
- Сменный прикус
- Переключатель «Беззубый»
**📦 Выпадающее меню дополнительных статусов:**
- Верхние/нижние циркониевые мосты (12-22, 13-23, 16-26, полная дуга)
- Верхние/нижние металлические мосты (12-22, 13-23, 16-26, полная дуга)
- Верхние/нижние частичные съёмные протезы
- Верхние/нижние полные съёмные протезы
- Верхние/нижние балочные протезы с имплантатами
**🦷 Панель редактора зуба** (для выбранного зуба/зубов, сгруппирована в сворачиваемые карточки):
- **Базовая строка:** выбор зуба (базовый тип, включая варианты сломанной коронки) и субстрат зуба (натуральный/radix/сломанный/подготовлен под коронку)
- **Строка реставрации:** комбинированный выпадающий список реставрации «Fix: …» / «Kivehető: …» (фиксированные опции `restorationType`×`restorationMaterial` плюс опции аттачмента/съёмного протеза `prosthesis`, ограниченные видом зуба); флажок краевой негерметичности коронки (только коронка/мост); флажки локализации сломанной коронки; переключатели «требуется коронка» / «требуется замена коронки»
- **Строка стирания и изменения цвета:** выпадающий список типа стирания режущего края/окклюзионной поверхности, выпадающий список типа пришеечного стирания, выпадающий список причины изменения цвета (каждый переключается на простой переключатель да/нет в режиме Настройки → Детали зуба → упрощённый режим)
- **Карточка ортодонтии:** аппарат, мезиальный/дистальный дрейф, вертикальное перемещение (экструзия/интрузия), переключатель ротации — отображается на присутствующем натуральном зубе
- **Карточка кариеса:** выпадающий список режима глубины кариеса, флажок подкоронкового кариеса, выпадающий список тяжести кариеса корня и селектор поверхностей кариеса B/M/O/D/L с контекстным всплывающим окном глубины ICDAS/CARS и значком рентгенологической глубины
- **Карточка пломб:** выпадающий список материала пломбы, селектор пломбы по поверхностям (с материалом по каждой поверхности), индикатор дефекта пломбы по поверхностям (краевой/перелом/стирание), подсказки о вторичном кариесе и дефекте пломбы
- **Карточка «Корень и пародонт»:** объединённый селектор «Статус пульпы / эндо», селектор апикального диагноза, селектор подтипа периапикального очага (только симптоматический/бессимптомный апикальный периодонтит), селектор типа резорбции корня, селектор степени подвижности, селектор статуса периимплантных тканей (только имплантаты)
- **Специальные индикаторы:** план/лунка после удаления, закрытый дефект после удаления, герметизация фиссур, потеря контактного пункта, зубной камень, парапульпарный штифт, эндодонтическая резекция, опора моста
### 🦷 Типы зубов и состояния
**Выбор зуба (базовый тип):**
| Значение | Описание |
|---|---|
| `none` | Отсутствующий зуб |
| `tooth-base` | Постоянный зуб |
| `milktooth` | Молочный зуб |
| `implant` | Имплантат |
| `tooth-under-gum` | Поддесневой (непрорезавшийся) зуб |
**Варианты сломанного зуба:**
`tooth-broken-inicisal`, `tooth-broken-distal-inicisal`, `tooth-broken-distal`, `tooth-broken-mesial-distal-inicisal`, `tooth-broken-mesial-distal`, `tooth-broken-mesial-inicisal`, `tooth-broken-mesial`, `no-tooth-after-extraction`
**Субстрат зуба (постоянные зубы):**
`natural` (по умолчанию), `radix` (корневой остаток), `broken`, `crownprep` (подготовлен под коронку)
**Тип реставрации (постоянные зубы):**
`none`, `crown`, `inlay`, `onlay` (только окклюзионный вид), `veneer`, `bridge`
**Материал реставрации (постоянные зубы):**
`none`, `emax`, `gold`, `gradia`, `zircon`, `metal`, `metal-ceramic` (устаревшие коронки `metal` мигрируют сюда), `telescope`, `temporary`
**Опции реставрации ограничены видом зуба** (`restorationOptions()` в `src/registry/restorations.ts`): имплантат предлагает только типы реставрации `crown`/`bridge` (в сочетании со слоем имплантационного коннектора) плюс пять записей аттачмента `prosthesis`, перечисленных ниже; отсутствующий зуб/дефект предлагает только тело моста `bridge` плюс две записи съёмного протеза `prosthesis`; субстрат `radix` полностью скрывает элемент управления реставрацией. Устаревшие плоские поля `crownMaterial`/`bridgeUnit` (значения аттачмента имплантата/моста до версии 1.14) исключены из актуальной модели — принимаются только как путь миграции для чтения старых данных (только для чтения).
**Протезирование** (`prosthesis`; независимая ось съёмного/аттачментного протезирования, отображается как записи «Kivehető:» в комбинированном выпадающем списке реставрации):
`none`, `healing-abutment`, `locator`, `locator-denture`, `bar`, `bar-denture` (аттачменты имплантата, с покрывным протезом или без него), `removable-partial`, `removable-full` (съёмные протезы с опорой на зубы на отсутствующем зубе/дефекте). У зуба может быть либо фиксированная реставрация, либо протез, но никогда оба одновременно — установка одного очищает другое.
**Краевая негерметичность коронки** (`crownLeakage`; логическое значение): отображается только когда `restorationType` равен `crown` или `bridge`; активирует слой изображения `crown-leakage`.
**Эндодонтические варианты (постоянные зубы):**
`none`, `endo-medical-filling`, `endo-filling`, `endo-filling-incomplete`, `endo-glass-pin`, `endo-metal-pin`
**Эндодонтические варианты (молочные зубы):**
`none`, `endo-medical-filling`
`endo` и `pulpDx` отображаются через единый объединённый селектор `
