@olddevs/ui 4.3.0 → 4.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (182) hide show
  1. package/CHANGELOG.md +36 -0
  2. package/dist/editor/RichTextEditor.d.ts +11 -4
  3. package/dist/editor/RichTextEditor.d.ts.map +1 -1
  4. package/dist/editor/RichTextEditor.js +124 -60
  5. package/dist/editor/RichTextEditor.js.map +1 -1
  6. package/dist/editor/RichTextView.d.ts +2 -1
  7. package/dist/editor/RichTextView.d.ts.map +1 -1
  8. package/dist/editor/RichTextView.js.map +1 -1
  9. package/dist/editor/core/containers.d.ts +2 -6
  10. package/dist/editor/core/containers.d.ts.map +1 -1
  11. package/dist/editor/core/containers.js +2 -1
  12. package/dist/editor/core/containers.js.map +1 -1
  13. package/dist/editor/core/customTool.d.ts +8 -2
  14. package/dist/editor/core/customTool.d.ts.map +1 -1
  15. package/dist/editor/core/customTool.js.map +1 -1
  16. package/dist/editor/core/customToolEngine.d.ts +9 -1
  17. package/dist/editor/core/customToolEngine.d.ts.map +1 -1
  18. package/dist/editor/core/customToolEngine.js +12 -0
  19. package/dist/editor/core/customToolEngine.js.map +1 -1
  20. package/dist/editor/core/extensions.d.ts.map +1 -1
  21. package/dist/editor/core/extensions.js +1 -1
  22. package/dist/editor/core/extensions.js.map +1 -1
  23. package/dist/editor/core/handle.d.ts +18 -5
  24. package/dist/editor/core/handle.d.ts.map +1 -1
  25. package/dist/editor/core/handle.js +2 -13
  26. package/dist/editor/core/handle.js.map +1 -1
  27. package/dist/editor/core/handleWatchers.d.ts +36 -0
  28. package/dist/editor/core/handleWatchers.d.ts.map +1 -0
  29. package/dist/editor/core/handleWatchers.js +29 -0
  30. package/dist/editor/core/handleWatchers.js.map +1 -0
  31. package/dist/editor/core/nodeNames.d.ts +7 -0
  32. package/dist/editor/core/nodeNames.d.ts.map +1 -0
  33. package/dist/editor/core/nodeNames.js +2 -0
  34. package/dist/editor/core/nodeNames.js.map +1 -0
  35. package/dist/editor/core/schema.d.ts.map +1 -1
  36. package/dist/editor/core/schema.js +4 -2
  37. package/dist/editor/core/schema.js.map +1 -1
  38. package/dist/editor/core/toolCommands.d.ts +78 -0
  39. package/dist/editor/core/toolCommands.d.ts.map +1 -0
  40. package/dist/editor/core/toolCommands.js +2 -0
  41. package/dist/editor/core/toolCommands.js.map +1 -0
  42. package/dist/editor/core/toolDefinition.d.ts +139 -0
  43. package/dist/editor/core/toolDefinition.d.ts.map +1 -0
  44. package/dist/editor/core/toolDefinition.js +28 -0
  45. package/dist/editor/core/toolDefinition.js.map +1 -0
  46. package/dist/editor/core/toolDescriptor.d.ts +71 -2
  47. package/dist/editor/core/toolDescriptor.d.ts.map +1 -1
  48. package/dist/editor/core/toolDescriptor.js +6 -2
  49. package/dist/editor/core/toolDescriptor.js.map +1 -1
  50. package/dist/editor/core/toolOptions.d.ts +157 -0
  51. package/dist/editor/core/toolOptions.d.ts.map +1 -0
  52. package/dist/editor/core/toolOptions.js +21 -0
  53. package/dist/editor/core/toolOptions.js.map +1 -0
  54. package/dist/editor/core/toolState.d.ts +46 -0
  55. package/dist/editor/core/toolState.d.ts.map +1 -0
  56. package/dist/editor/core/toolState.js +2 -0
  57. package/dist/editor/core/toolState.js.map +1 -0
  58. package/dist/editor/core/tools.d.ts +10 -3
  59. package/dist/editor/core/tools.d.ts.map +1 -1
  60. package/dist/editor/core/tools.js +2 -1
  61. package/dist/editor/core/tools.js.map +1 -1
  62. package/dist/editor/core/viewIsland.d.ts.map +1 -1
  63. package/dist/editor/core/viewIsland.js +2 -1
  64. package/dist/editor/core/viewIsland.js.map +1 -1
  65. package/dist/editor/features/builtins.d.ts +9 -4
  66. package/dist/editor/features/builtins.d.ts.map +1 -1
  67. package/dist/editor/features/builtins.js +36 -7
  68. package/dist/editor/features/builtins.js.map +1 -1
  69. package/dist/editor/features/search/SearchPanel.d.ts.map +1 -1
  70. package/dist/editor/features/search/SearchPanel.js +26 -12
  71. package/dist/editor/features/search/SearchPanel.js.map +1 -1
  72. package/dist/editor/features/search/revealMatch.d.ts +16 -0
  73. package/dist/editor/features/search/revealMatch.d.ts.map +1 -1
  74. package/dist/editor/features/search/revealMatch.js +22 -0
  75. package/dist/editor/features/search/revealMatch.js.map +1 -1
  76. package/dist/editor/features/search/searchPlugin.d.ts +8 -3
  77. package/dist/editor/features/search/searchPlugin.d.ts.map +1 -1
  78. package/dist/editor/features/search/searchPlugin.js +17 -6
  79. package/dist/editor/features/search/searchPlugin.js.map +1 -1
  80. package/dist/editor/features/search/searchSnapshot.d.ts +14 -0
  81. package/dist/editor/features/search/searchSnapshot.d.ts.map +1 -0
  82. package/dist/editor/features/search/searchSnapshot.js +17 -0
  83. package/dist/editor/features/search/searchSnapshot.js.map +1 -0
  84. package/dist/editor/features/search/searchTool.d.ts +3 -0
  85. package/dist/editor/features/search/searchTool.d.ts.map +1 -1
  86. package/dist/editor/features/search/searchTool.js +30 -1
  87. package/dist/editor/features/search/searchTool.js.map +1 -1
  88. package/dist/editor/features/toc/RichTextToc.d.ts +91 -0
  89. package/dist/editor/features/toc/RichTextToc.d.ts.map +1 -0
  90. package/dist/editor/features/toc/RichTextToc.js +417 -0
  91. package/dist/editor/features/toc/RichTextToc.js.map +1 -0
  92. package/dist/editor/features/toc/documentHeadings.d.ts +30 -0
  93. package/dist/editor/features/toc/documentHeadings.d.ts.map +1 -0
  94. package/dist/editor/features/toc/documentHeadings.js +20 -0
  95. package/dist/editor/features/toc/documentHeadings.js.map +1 -0
  96. package/dist/editor/features/toc/headings.d.ts +35 -0
  97. package/dist/editor/features/toc/headings.d.ts.map +1 -0
  98. package/dist/editor/features/toc/headings.js +27 -0
  99. package/dist/editor/features/toc/headings.js.map +1 -0
  100. package/dist/editor/features/toc/stickyOffset.d.ts +3 -0
  101. package/dist/editor/features/toc/stickyOffset.d.ts.map +1 -0
  102. package/dist/editor/features/toc/stickyOffset.js +14 -0
  103. package/dist/editor/features/toc/stickyOffset.js.map +1 -0
  104. package/dist/editor/features/toc/tocSnapshot.d.ts +10 -0
  105. package/dist/editor/features/toc/tocSnapshot.d.ts.map +1 -0
  106. package/dist/editor/features/toc/tocSnapshot.js +8 -0
  107. package/dist/editor/features/toc/tocSnapshot.js.map +1 -0
  108. package/dist/editor/features/toc/tocTool.d.ts +6 -0
  109. package/dist/editor/features/toc/tocTool.d.ts.map +1 -0
  110. package/dist/editor/features/toc/tocTool.js +21 -0
  111. package/dist/editor/features/toc/tocTool.js.map +1 -0
  112. package/dist/editor/hooks/useRichTextToolState.d.ts +43 -0
  113. package/dist/editor/hooks/useRichTextToolState.d.ts.map +1 -0
  114. package/dist/editor/hooks/useRichTextToolState.js +77 -0
  115. package/dist/editor/hooks/useRichTextToolState.js.map +1 -0
  116. package/dist/editor/index.d.ts +10 -0
  117. package/dist/editor/index.d.ts.map +1 -1
  118. package/dist/editor/index.js +4 -0
  119. package/dist/editor/index.js.map +1 -1
  120. package/dist/i18n/defaults.d.ts.map +1 -1
  121. package/dist/i18n/defaults.js +1 -0
  122. package/dist/i18n/defaults.js.map +1 -1
  123. package/dist/i18n/messages.d.ts +5 -0
  124. package/dist/i18n/messages.d.ts.map +1 -1
  125. package/dist/locales/ru.d.ts.map +1 -1
  126. package/dist/locales/ru.js +1 -0
  127. package/dist/locales/ru.js.map +1 -1
  128. package/docs/api/editor-extension.en.md +223 -23
  129. package/docs/api/editor-extension.md +224 -22
  130. package/docs/api/messages.en.md +743 -0
  131. package/docs/api/messages.md +1 -0
  132. package/docs/api/migration-notes.en.md +36 -1
  133. package/docs/api/migration-notes.md +35 -0
  134. package/docs/api/utilities.en.md +233 -0
  135. package/docs/components/content/rich-text-toc.en.md +132 -0
  136. package/docs/components/content/rich-text-toc.md +131 -0
  137. package/docs/components/index.en.md +3 -2
  138. package/docs/components/index.md +2 -1
  139. package/docs/components/inputs/rich-text-editor.en.md +277 -43
  140. package/docs/components/inputs/rich-text-editor.md +247 -11
  141. package/docs/conventions.en.md +318 -0
  142. package/docs/getting-started.en.md +7 -7
  143. package/docs/getting-started.md +6 -6
  144. package/docs/glossary.en.md +52 -47
  145. package/docs/glossary.md +51 -46
  146. package/docs/index.en.md +53 -0
  147. package/llms.txt +1 -0
  148. package/package.json +1 -1
  149. package/src/editor/RichTextEditor.tsx +197 -38
  150. package/src/editor/RichTextView.tsx +2 -1
  151. package/src/editor/core/containers.ts +8 -6
  152. package/src/editor/core/customTool.ts +8 -2
  153. package/src/editor/core/customToolEngine.ts +20 -1
  154. package/src/editor/core/extensions.ts +2 -1
  155. package/src/editor/core/handle.ts +26 -23
  156. package/src/editor/core/handleWatchers.ts +72 -0
  157. package/src/editor/core/nodeNames.ts +7 -0
  158. package/src/editor/core/schema.ts +5 -2
  159. package/src/editor/core/toolCommands.ts +85 -0
  160. package/src/editor/core/toolDefinition.ts +208 -0
  161. package/src/editor/core/toolDescriptor.ts +94 -3
  162. package/src/editor/core/toolOptions.ts +211 -0
  163. package/src/editor/core/toolState.ts +56 -0
  164. package/src/editor/core/tools.ts +12 -3
  165. package/src/editor/core/viewIsland.ts +5 -4
  166. package/src/editor/features/builtins.ts +72 -13
  167. package/src/editor/features/search/SearchPanel.tsx +38 -14
  168. package/src/editor/features/search/revealMatch.ts +45 -0
  169. package/src/editor/features/search/searchPlugin.ts +40 -11
  170. package/src/editor/features/search/searchSnapshot.ts +29 -0
  171. package/src/editor/features/search/searchTool.ts +51 -1
  172. package/src/editor/features/toc/RichTextToc.tsx +810 -0
  173. package/src/editor/features/toc/documentHeadings.ts +59 -0
  174. package/src/editor/features/toc/headings.ts +77 -0
  175. package/src/editor/features/toc/stickyOffset.ts +21 -0
  176. package/src/editor/features/toc/tocSnapshot.ts +24 -0
  177. package/src/editor/features/toc/tocTool.ts +41 -0
  178. package/src/editor/hooks/useRichTextToolState.ts +153 -0
  179. package/src/editor/index.ts +21 -0
  180. package/src/i18n/defaults.ts +1 -0
  181. package/src/i18n/messages.ts +5 -0
  182. package/src/locales/ru.ts +1 -0
package/docs/glossary.md CHANGED
@@ -131,49 +131,54 @@
131
131
  Термины `RichTextEditor` и `RichTextView` (вход `@olddevs/ui/editor`). Здесь особенно легко
132
132
  взять слово из соседнего редактора (плагин, сервис, нода) — оно заводит второй смысл.
133
133
 
134
- | Термин | Значение | Не путать с |
135
- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
136
- | **Редактор** | `RichTextEditor` — поле ввода форматированного текста | Редактором кода: его в ките нет, показ кода — `CodeView` |
137
- | **Просмотр** | `RichTextView` — только чтение сохранённого Документа | `readOnly`-режимом Редактора: тот держит движок, Просмотр — нет |
138
- | **Документ** | Значение Редактора: HTML-строка, ограниченная Схемой | JSON-деревом ProseMirror в движке — оно внутреннее; наружу оно выходит только JSON-конвертом |
139
- | **JSON-конверт** | Документ как JSON для файла и шаблона: `{ format: "olddevs-rich-text", version, doc }` (`getJSON()`, `setJSON()`, `defaultValue`), без потерь и через Схему | Значением Редактора — значение остаётся HTML; голым деревом `editor.getJSON()` без конверта |
140
- | **Схема** | Белый список Блоков, Меток и атрибутов, которые Редактор принимает и отдаёт | Санитизацией на сервере — её делает потребитель (`sanitizeRichText`) |
141
- | **Блок** | Структурный элемент Документа: абзац, заголовок, список, таблица, картинка… | Меткой |
142
- | **Метка** | Строчное форматирование внутри Блока: жирный, ссылка, цвет… | Блоком |
143
- | **Атом** | Блок или строчный элемент, который выделяется, переносится и удаляется целиком: картинка (подпись внутри неё правится), разделитель, мягкий перенос, упоминание. Всегда делает поле непустым | Пустым Блоком: абзац без текста — не Атом и содержимым не считается |
144
- | **Текст атома** | Строка, которой Атом представлен в тексте Документа: её отдают `getText` и `getSelectedText`, её длина — вес Атома в `maxLength`, ею Атом выгружается в Markdown без своих правил. У картинки — текст подписи, у разделителя — пустая строка | Атрибутом Блока |
145
- | **Раскладка** | Блок из колонок (Инструмент `layout`): шесть вариантов — от одной до четырёх равных колонок, 60/40 и 40/60. Только верхнего уровня, в себя не вкладывается; колонка для своих Блоков — то же, что Документ | Таблицей: у той строки и ячейки данных, а колонки Раскладки — вёрстка Документа. `Grid` кита — сеткой экрана, а не Блоком |
146
- | **Обёртка** | Блок, который собирает группу Блоков (Инструмент `wrapper`, `div` с `data-block="wrapper"`): их двигают, дублируют и удаляют одним Блоком. Без Тона Обёртки своего вида нет — пунктир только в Редакторе. Обёртка и Раскладка в Обёртку не вкладываются | Цитатой: у той свой вид и смысл в Документе, а Обёртка без тона — только группировка |
147
- | **Тон Обёртки** | Оформление Обёртки заметкой (`data-tone`): фон и полоса слева одного из пяти тонов словаря `Tone` — «Заметка», «Совет», «Важно», «Внимание», «Осторожно». Выбирается в «Тон ›» Ручки Блока, одинаков в Редакторе и Просмотре, в Markdown выгружается GitHub alert (то, что GitHub и Notion называют callout) | Тоном Сообщения поля (`status` или `error`). Смыслом: ролей и `aria-*` тон не несёт, смысл заметки пишется словом в тексте |
148
- | **Панель** | Набор кнопок форматирования; вид задаёт `toolbar`. **Фиксированная** (`fixed`, по умолчанию) — над полем, липнет при прокрутке; **плавающая** (`floating`) — те же кнопки над непустым выделением. При `bubble` Панели нет — её место занимает Меню выделения, при `none` нет ни того, ни другого. На сенсорном экране Панель всегда фиксированная | `Toolbar` кита — Примитивом, из которого Панель собрана |
149
- | **Меню вставки** | Список «Добавить» и «Превратить в»: открывается по `/` в тексте и по кнопке «+» | Контекстным меню браузера |
150
- | **Меню выделения** | Компактная плашка на инверсной поверхности над непустым выделением: «¶», списки, жирный, курсив, подчёркнутый, цвет, «…», ссылка, эмодзи; состав задан китом. Стоит вместо Панели при `toolbar="bubble"` и поверх фиксированной Панели — там её выключает `selectionMenu={false}`. На сенсорном экране её нет | Плавающей Панелью: у той полный набор кнопок |
151
- | **Ручка Блока** | «⋮» у Блока с кареткой и её меню действий над Блоком целиком: «Добавить ›», «Формат ›», «Вверх», «Вниз», «Дублировать», «Удалить» | Панелью: та работает с выделением, а не с Блоком |
152
- | **Пункт вставки** | Строка Меню вставки: вставляет Блок или превращает текущий. Один пункт виден и по `/`, и по «+», и в Ручке Блока | Кнопкой Панели |
153
- | **Действие над Блоком** | Пункт меню Ручки Блока, который работает с Блоком целиком, например «Дублировать» | Кнопкой: та работает с выделением |
154
- | **Справочник сочетаний** | Поповер «команда — сочетание» только для чтения за последней кнопкой фиксированной Панели. Строки — команды включённых Инструментов, своих тоже; на телефоне кнопки нет | `CommandPalette` кита: строки Справочника сочетаний не нажимаются. `ShortcutsHelp` кита: тот — сочетания экрана, а не Редактора |
155
- | **HTML-режим** | Режим Инструмента `source`: кнопка «HTML» на фиксированной Панели заменяет Документ полем с его HTML. Текст поля проходит Схему и становится Документом одной правкой — при выходе из режима, `blur`, отправке формы и чтении через Хэндл | HTML-соглашением: то — форма своего в Документе, а не режим. `CodeView`: тот показывает код, а поле HTML правится |
156
- | **Стекло** | Полупрозрачная заливка с размытием фона у всего, что Редактор показывает поверх Документа: плавающая Панель, Меню выделения, меню, поповеры, Карточка у текста. Цвет — токен своей поверхности; при `prefers-reduced-transparency`, `prefers-contrast: more` и на iOS заливка сплошная | `Menu` и `Popover` кита вне Редактора: те остаются сплошными |
157
- | **UI-запись** | Элемент интерфейса своего Инструмента, описанный данными: кнопка, Пункт вставки, Действие над Блоком или Карточка у текста. Рисует её кит в Отведённом месте; выключенный Инструмент убирает и свои записи | React-узлом в интерфейсе: произвольный React допускается только в содержимом поповера кнопки и Карточки у текста |
158
- | **Отведённое место** | Одно место на поверхности, где стоят записи своих Инструментов, в порядке `tools`: группа Панели перед «Отменить», конец раздела Меню вставки, секция Ручки Блока перед «Удалить» | Позицией относительно встроенной кнопки: id встроенных публичным API не являются |
159
- | **Пресет** | Готовый набор встроенных Инструментов: `full` или `basic` (`RICH_TEXT_PRESETS`). Не замороженный список: новый встроенный приходит в него minor-версией | Точным списком `tools`: его состав меняет только экран |
160
- | **Инструмент** | Одна возможность Редактора: её Блоки и Метки, их правила в Схеме и место в интерфейсе, например `table`. Встроенный задаётся именем, свой — описанием | Кнопкой: выключенный Инструмент убирает и Блок из Схемы. Плагином Redactor: тот — класс поведения над DOM без Схемы |
161
- | **Свой Инструмент** | Инструмент, который описывает потребитель (`CustomTool`): правила Схемы данными, Часть для движка и UI-записи. Передаётся в `tools` вперемешку с именами кита | Внутренним описанием кита: то — надмножество публичной формы для встроенных, наружу не экспортируется |
162
- | **Префикс потребителя** | Начало имени всего своего — Инструмента, его Блоков, Меток и атрибутов — до подчёркивания: `acme_mergeTag`, `data-acme_size`. В именах кита подчёркивания нет, поэтому своё и встроенное не совпадают ни в наборе, ни в Документе | Пресетом: тот — набор встроенных Инструментов, а не пространство имён |
163
- | **HTML-соглашение** | Форма своего в Документе: Блок — `div` или `span` с `data-block`, Метка — `span` с `data-mark`, атрибуты — `data-<префикс>_<имя>`. Заморожено: расширяется только добавлением | Тегами Схемы кита (`p`, `table`, `img`): свой Блок их занять не может |
164
- | **Признак Блока** | Свойство Блока, которое понимает только кит, а не движок: «контейнер» (детям своя Ручка), «можно превратить в», «Атом без меню форматирования» | Атрибутом Блока: тот хранится в Документе |
165
- | **Часть для движка** | То в описании Инструмента, что нужно только живому Редактору: расширения Tiptap и вид узла. Подаётся сразу или Загрузчиком | Правилами Схемы: те — данные, их читают сервер и Просмотр без движка |
166
- | **Загрузчик** | Функция с динамическим импортом вместо Части для движка: `engine: () => import(…)`. Так же грузятся тяжёлые встроенные вне `basic` — Блок кода и таблица | Предзагрузкой (`modulepreload`): её кит не публикует, ставит потребитель |
167
- | **Хэндл** | Императивный доступ кода экрана к Редактору через `ref`: вставка у каретки, чтение, фокус, история | Сервисами Redactor: те — внутренности движка, а не API экрана |
168
- | **Готовность** | Момент, когда движок создан и Загрузчики всех включённых Инструментов, своих и встроенных, отработали: с него методы Хэндла действуют, а не молчат. Наступает один раз за монтаж, о нём сообщает `onReady` | Гидратацией: после неё движок может ещё ждать Загрузчики |
169
- | **Фокус поля** | Фокус внутри Редактора целиком: Документ, Панель, поповеры кита, поле HTML. Переход между ними Фокус поля не теряет; `onFocus` и `onBlur` — о нём | Фокусом Документа (`focus` и `blur` движка): клик в Панель его снимает |
170
- | **Правка автора** | Изменение Документа, равное набору с клавиатуры: шаг истории, `onChange` после задержки, предел символов действует. Сюда же вставка, отмена и повтор из Хэндла | Заменой снаружи |
171
- | **Замена снаружи** | Подмена Документа целиком (`value`, `clear()`, `setMarkdown()`, `setJSON()`): предел символов не режет; `onChange` сразу у `clear()`, `setMarkdown()` и `setJSON()`, на новый `value` не вызывается | Правкой автора |
172
- | **Скелет** | Вид Редактора до Готовности: рамка поля, место Панели и Документ: очищенный Схемой, он выведен статичным HTML с тем же классом и ритмом, что Документ движка, без ввода. На сервере — рамка без Документа. Сбой Загрузчика превращает Скелет в ошибку поля с «Повторить» | Просмотром: тот — отдельный компонент только для чтения, а Скелет — состояние Редактора, которое сменяется движком. Компонентом `Skeleton` кита — заглушкой загрузки |
173
- | **Строка статуса** | Строка внутри рамки поля под Документом: слева содержимое экрана (`status`: число слов, «Сохранено», соавтор), справа счётчик символов кита | Сообщением поля: строка показывает длительное состояние экрана, а не событие |
174
- | **Сообщение поля** | Одно событие, привязанное к полю (`showNotice`): тон `status` (только озвучивается) или `error` (видимая строка под полем до следующей Правки автора). Новое заменяет прежнее | Тостом кита: тот глобален и к полю не привязан |
175
- | **Карточка у текста** | Немодальная карточка под диапазоном Документа, который объявил свой Инструмент (`textCards`): комментарий, подсказка по результатам проверки текста. Открывается кареткой или щелчком, фокус остаётся в тексте | Поповером кнопки: его открывает кнопка, а Карточку — место Документа |
176
- | **Символ-триггер** | Свой символ Инструмента (`trigger`), набор которого в начале Блока или после пробела открывает список пунктов у каретки, как `/`: `@` для упоминаний, `#` для тегов. Выбор заменяет набранное `@запрос` своим узлом | Меню вставки по `/`: то — встроенное, а свой символ задаёт Инструмент |
177
- | **Лист** | Светлая область Документа в любой теме приложения (`surface="paper"`) — для текста, который уйдёт из приложения светлым: письмо, печать, PDF. Панель, меню и рамка поля остаются в теме приложения; Просмотр с тем же `surface` показывает тот же Лист | Темой `light`: та меняет всё приложение, Лист — только Документ |
178
- | **Остров** | Клиентский кусок Просмотра, который после монтирования оживляет Блок в уже показанном HTML: кнопка «Копировать» у Блока кода, `island` своего Блока | Видом узла: тот живёт только в движке Редактора |
179
- | **Гнездо** | Место в показанном HTML, куда Остров монтирует живой элемент: шапка Блока кода, в которую встаёт кнопка «Копировать» | Отведённым местом: то — место в интерфейсе Редактора для записей Инструментов |
134
+ | Термин | Значение | Не путать с |
135
+ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
136
+ | **Редактор** | `RichTextEditor` — поле ввода форматированного текста | Редактором кода: его в ките нет, показ кода — `CodeView` |
137
+ | **Просмотр** | `RichTextView` — только чтение сохранённого Документа | `readOnly`-режимом Редактора: тот держит движок, Просмотр — нет |
138
+ | **Оглавление** | `RichTextToc`: список заголовков Документа рядом с Просмотром или Редактором. Свёрнуто — полоса штрихов, раскрыто — список, клик по пункту ведёт к заголовку | `Heading` кита и навигацией сайта документации |
139
+ | **Документ** | Значение Редактора: HTML-строка, ограниченная Схемой | JSON-деревом ProseMirror в движке — оно внутреннее; наружу оно выходит только JSON-конвертом |
140
+ | **JSON-конверт** | Документ как JSON для файла и шаблона: `{ format: "olddevs-rich-text", version, doc }` (`getJSON()`, `setJSON()`, `defaultValue`), без потерь и через Схему | Значением Редактора — значение остаётся HTML; голым деревом `editor.getJSON()` без конверта |
141
+ | **Схема** | Белый список Блоков, Меток и атрибутов, которые Редактор принимает и отдаёт | Санитизацией на сервере — её делает потребитель (`sanitizeRichText`) |
142
+ | **Блок** | Структурный элемент Документа: абзац, заголовок, список, таблица, картинка… | Меткой |
143
+ | **Метка** | Строчное форматирование внутри Блока: жирный, ссылка, цвет… | Блоком |
144
+ | **Атом** | Блок или строчный элемент, который выделяется, переносится и удаляется целиком: картинка (подпись внутри неё правится), разделитель, мягкий перенос, упоминание. Всегда делает поле непустым | Пустым Блоком: абзац без текста — не Атом и содержимым не считается |
145
+ | **Текст атома** | Строка, которой Атом представлен в тексте Документа: её отдают `getText` и `getSelectedText`, её длина — вес Атома в `maxLength`, ею Атом выгружается в Markdown без своих правил. У картинки — текст подписи, у разделителя — пустая строка | Атрибутом Блока |
146
+ | **Раскладка** | Блок из колонок (Инструмент `layout`): шесть вариантов — от одной до четырёх равных колонок, 60/40 и 40/60. Только верхнего уровня, в себя не вкладывается; колонка для своих Блоков — то же, что Документ | Таблицей: у той строки и ячейки данных, а колонки Раскладки — вёрстка Документа. `Grid` кита — сеткой экрана, а не Блоком |
147
+ | **Обёртка** | Блок, который собирает группу Блоков (Инструмент `wrapper`, `div` с `data-block="wrapper"`): их двигают, дублируют и удаляют одним Блоком. Без Тона Обёртки своего вида нет — пунктир только в Редакторе. Обёртка и Раскладка в Обёртку не вкладываются | Цитатой: у той свой вид и смысл в Документе, а Обёртка без тона — только группировка |
148
+ | **Тон Обёртки** | Оформление Обёртки заметкой (`data-tone`): фон и полоса слева одного из пяти тонов словаря `Tone` — «Заметка», «Совет», «Важно», «Внимание», «Осторожно». Выбирается в «Тон ›» Ручки Блока, одинаков в Редакторе и Просмотре, в Markdown выгружается GitHub alert (то, что GitHub и Notion называют callout) | Тоном Сообщения поля (`status` или `error`). Смыслом: ролей и `aria-*` тон не несёт, смысл заметки пишется словом в тексте |
149
+ | **Панель** | Набор кнопок форматирования; вид задаёт `toolbar`. **Фиксированная** (`fixed`, по умолчанию) — над полем, липнет при прокрутке; **плавающая** (`floating`) — те же кнопки над непустым выделением. При `bubble` Панели нет — её место занимает Меню выделения, при `none` нет ни того, ни другого. На сенсорном экране Панель всегда фиксированная | `Toolbar` кита — Примитивом, из которого Панель собрана |
150
+ | **Меню вставки** | Список «Добавить» и «Превратить в»: открывается по `/` в тексте и по кнопке «+» | Контекстным меню браузера |
151
+ | **Меню выделения** | Компактная плашка на инверсной поверхности над непустым выделением: «¶», списки, жирный, курсив, подчёркнутый, цвет, «…», ссылка, эмодзи; состав задан китом. Стоит вместо Панели при `toolbar="bubble"` и поверх фиксированной Панели — там её выключает `selectionMenu={false}`. На сенсорном экране её нет | Плавающей Панелью: у той полный набор кнопок |
152
+ | **Ручка Блока** | «⋮» у Блока с кареткой и её меню действий над Блоком целиком: «Добавить ›», «Формат ›», «Вверх», «Вниз», «Дублировать», «Удалить» | Панелью: та работает с выделением, а не с Блоком |
153
+ | **Пункт вставки** | Строка Меню вставки: вставляет Блок или превращает текущий. Один пункт виден и по `/`, и по «+», и в Ручке Блока | Кнопкой Панели |
154
+ | **Действие над Блоком** | Пункт меню Ручки Блока, который работает с Блоком целиком, например «Дублировать» | Кнопкой: та работает с выделением |
155
+ | **Справочник сочетаний** | Поповер «команда — сочетание» только для чтения за последней кнопкой фиксированной Панели. Строки — команды включённых Инструментов, своих тоже; на телефоне кнопки нет | `CommandPalette` кита: строки Справочника сочетаний не нажимаются. `ShortcutsHelp` кита: тот — сочетания экрана, а не Редактора |
156
+ | **HTML-режим** | Режим Инструмента `source`: кнопка «HTML» на фиксированной Панели заменяет Документ полем с его HTML. Текст поля проходит Схему и становится Документом одной правкой — при выходе из режима, `blur`, отправке формы и чтении через Хэндл | HTML-соглашением: то — форма своего в Документе, а не режим. `CodeView`: тот показывает код, а поле HTML правится |
157
+ | **Стекло** | Полупрозрачная заливка с размытием фона у всего, что Редактор показывает поверх Документа: плавающая Панель, Меню выделения, меню, поповеры, Карточка у текста. Цвет — токен своей поверхности; при `prefers-reduced-transparency`, `prefers-contrast: more` и на iOS заливка сплошная | `Menu` и `Popover` кита вне Редактора: те остаются сплошными |
158
+ | **UI-запись** | Элемент интерфейса своего Инструмента, описанный данными: кнопка, Пункт вставки, Действие над Блоком или Карточка у текста. Рисует её кит в Отведённом месте; выключенный Инструмент убирает и свои записи | React-узлом в интерфейсе: произвольный React допускается только в содержимом поповера кнопки и Карточки у текста |
159
+ | **Отведённое место** | Одно место на поверхности, где стоят записи своих Инструментов, в порядке `tools`: группа Панели перед «Отменить», конец раздела Меню вставки, секция Ручки Блока перед «Удалить» | Позицией относительно встроенной кнопки: id встроенных публичным API не являются |
160
+ | **Пресет** | Готовый набор встроенных Инструментов: `full` или `basic` (`RICH_TEXT_PRESETS`). Не замороженный список: новый встроенный приходит в него minor-версией | Точным списком `tools`: его состав меняет только экран |
161
+ | **Инструмент** | Одна возможность Редактора: её Блоки и Метки, их правила в Схеме и место в интерфейсе, например `table`. Встроенный задаётся именем, свой — описанием | Кнопкой: выключенный Инструмент убирает и Блок из Схемы. Плагином Redactor: тот — класс поведения над DOM без Схемы |
162
+ | **Свой Инструмент** | Инструмент, который описывает потребитель (`CustomTool`): правила Схемы данными, Часть для движка и UI-записи. Передаётся в `tools` вперемешку с именами кита | Внутренним описанием кита: то — надмножество публичной формы для встроенных, наружу не экспортируется |
163
+ | **Опции Инструмента** | Что экран задаёт Инструменту до создания движка: стартовые флажки Поиска, `offsetVar`, `levels` и `listWidth` Оглавления, `defaults` своего Инструмента (`defineTool`). Экран задаёт их записью `tool(…)`, кит читает один раз, при создании движка | `options` у расширения Tiptap: те задаёт сам автор расширения и читает Часть для движка, а Опции задаёт экран и читает кит. Пропами Редактора (`preset`, `maxHeight`): те настраивают поле, а не Инструмент |
164
+ | **Настроенный Инструмент** | Запись `tools`, которую возвращает `tool(name, options)` или `tool(definition, options)`: Инструмент вместе с его Опциями. Включает Инструмент без имени в `tools` и побеждает голое имя из Пресета | Определением `defineTool`: то описывает Инструмент, а Настроенный Инструмент — его включение с Опциями. Описанием встроенного: оно наружу не выходит, запись лишь называет Инструмент и несёт Опции |
165
+ | **Состояние Инструмента** | Снимок данных, который экран читает хуком `useRichTextToolState(ref, name)`: у Поиска — открыта ли панель, запрос, число совпадений и текущее, у Оглавления — заголовки и текущий раздел. Перерисовка только при смене снимка | `storage` у расширения Tiptap: то — изменяемое хранилище внутри движка, а Состояние только читается. `useRichTextEditorState`: тот берёт срез живого `editor` Tiptap, а не контракт Инструмента |
166
+ | **Команды Инструмента** | Что экран вызывает у Инструмента через `handle.tool(name)`: `tool("search")?.open()`, `tool("toc")?.jumpTo(2)`. Каждая возвращает `boolean`; `null` вместо объекта Команд — Инструмента нет в наборе, у него нет Команд или движок ещё не создан | Методами Хэндла (`insertHTML`, `focus`): те общие для любого `tools`, а Команды есть, только пока Инструмент включён. `editor.commands` и `commands` у Tiptap: те — команды движка, они следуют его мажору |
167
+ | **Префикс потребителя** | Начало имени всего своего — Инструмента, его Блоков, Меток и атрибутов — до подчёркивания: `acme_mergeTag`, `data-acme_size`. В именах кита подчёркивания нет, поэтому своё и встроенное не совпадают ни в наборе, ни в Документе | Пресетом: тот — набор встроенных Инструментов, а не пространство имён |
168
+ | **HTML-соглашение** | Форма своего в Документе: Блок — `div` или `span` с `data-block`, Метка — `span` с `data-mark`, атрибуты — `data-<префикс>_<имя>`. Заморожено: расширяется только добавлением | Тегами Схемы кита (`p`, `table`, `img`): свой Блок их занять не может |
169
+ | **Признак Блока** | Свойство Блока, которое понимает только кит, а не движок: «контейнер» (детям своя Ручка), «можно превратить в», «Атом без меню форматирования» | Атрибутом Блока: тот хранится в Документе |
170
+ | **Часть для движка** | То в описании Инструмента, что нужно только живому Редактору: расширения Tiptap и вид узла. Подаётся сразу или Загрузчиком | Правилами Схемы: те — данные, их читают сервер и Просмотр без движка |
171
+ | **Загрузчик** | Функция с динамическим импортом вместо Части для движка: `engine: () => import(…)`. Так же грузятся тяжёлые встроенные вне `basic` — Блок кода и таблица | Предзагрузкой (`modulepreload`): её кит не публикует, ставит потребитель |
172
+ | **Хэндл** | Императивный доступ кода экрана к Редактору через `ref`: вставка у каретки, чтение, фокус, история, Команды Инструментов (`tool(name)`) | Сервисами Redactor: те — внутренности движка, а не API экрана |
173
+ | **Готовность** | Момент, когда движок создан и Загрузчики всех включённых Инструментов, своих и встроенных, отработали: с него методы Хэндла действуют, а не молчат. Наступает один раз за монтаж, о нём сообщает `onReady` | Гидратацией: после неё движок может ещё ждать Загрузчики |
174
+ | **Фокус поля** | Фокус внутри Редактора целиком: Документ, Панель, поповеры кита, поле HTML. Переход между ними Фокус поля не теряет; `onFocus` и `onBlur` — о нём | Фокусом Документа (`focus` и `blur` движка): клик в Панель его снимает |
175
+ | **Правка автора** | Изменение Документа, равное набору с клавиатуры: шаг истории, `onChange` после задержки, предел символов действует. Сюда же вставка, отмена и повтор из Хэндла | Заменой снаружи |
176
+ | **Замена снаружи** | Подмена Документа целиком (`value`, `clear()`, `setMarkdown()`, `setJSON()`): предел символов не режет; `onChange` сразу у `clear()`, `setMarkdown()` и `setJSON()`, на новый `value` не вызывается | Правкой автора |
177
+ | **Скелет** | Вид Редактора до Готовности: рамка поля, место Панели и Документ: очищенный Схемой, он выведен статичным HTML с тем же классом и ритмом, что Документ движка, без ввода. На сервере — рамка без Документа. Сбой Загрузчика превращает Скелет в ошибку поля с «Повторить» | Просмотром: тот — отдельный компонент только для чтения, а Скелет — состояние Редактора, которое сменяется движком. Компонентом `Skeleton` кита — заглушкой загрузки |
178
+ | **Строка статуса** | Строка внутри рамки поля под Документом: слева содержимое экрана (`status`: число слов, «Сохранено», соавтор), справа счётчик символов кита | Сообщением поля: строка показывает длительное состояние экрана, а не событие |
179
+ | **Сообщение поля** | Одно событие, привязанное к полю (`showNotice`): тон `status` (только озвучивается) или `error` (видимая строка под полем до следующей Правки автора). Новое заменяет прежнее | Тостом кита: тот глобален и к полю не привязан |
180
+ | **Карточка у текста** | Немодальная карточка под диапазоном Документа, который объявил свой Инструмент (`textCards`): комментарий, подсказка по результатам проверки текста. Открывается кареткой или щелчком, фокус остаётся в тексте | Поповером кнопки: его открывает кнопка, а Карточку — место Документа |
181
+ | **Символ-триггер** | Свой символ Инструмента (`trigger`), набор которого в начале Блока или после пробела открывает список пунктов у каретки, как `/`: `@` для упоминаний, `#` для тегов. Выбор заменяет набранное `@запрос` своим узлом | Меню вставки по `/`: то — встроенное, а свой символ задаёт Инструмент |
182
+ | **Лист** | Светлая область Документа в любой теме приложения (`surface="paper"`) — для текста, который уйдёт из приложения светлым: письмо, печать, PDF. Панель, меню и рамка поля остаются в теме приложения; Просмотр с тем же `surface` показывает тот же Лист | Темой `light`: та меняет всё приложение, Лист — только Документ |
183
+ | **Остров** | Клиентский кусок Просмотра, который после монтирования оживляет Блок в уже показанном HTML: кнопка «Копировать» у Блока кода, `island` своего Блока | Видом узла: тот живёт только в движке Редактора |
184
+ | **Гнездо** | Место в показанном HTML, куда Остров монтирует живой элемент: шапка Блока кода, в которую встаёт кнопка «Копировать» | Отведённым местом: то — место в интерфейсе Редактора для записей Инструментов |
package/docs/index.en.md ADDED
@@ -0,0 +1,53 @@
1
+ ---
2
+ sourceHash: 7fafe8d11f89
3
+ ---
4
+
5
+ # `@olddevs/ui` Reference
6
+
7
+ This Reference is the contract for developers and AI agents who use the package's public API. The source of
8
+ truth for the exports is [`src/index.ts`](../src/index.ts). Component sources, tests and Storybook confirm the
9
+ behavior claims on the pages.
10
+
11
+ ## Start here
12
+
13
+ 1. [Install the package](getting-started.md): imports, CSS and Tailwind 4.
14
+ 2. [Choose a component](component-selection.md): pick the meaning first, not a similar look.
15
+ 3. [Shared conventions](conventions.md): the prop vocabulary, controlled state and the limits of the public API.
16
+ 4. [Glossary](glossary.md): the terms of the kit and the Editor, and what not to confuse them with.
17
+ 5. [Accessibility](accessibility.md): the required rules for names, focus and the keyboard.
18
+ 6. [Themes, tokens and brands](theming.md): the four token layers and how to add your own brand in one CSS block.
19
+ 7. [Palette](palette.md): the palette primitive values and the roles by theme, in one table.
20
+ 8. [Localization](i18n.md): the provider, the message catalog and how to connect to the consumer's `I18nProvider`.
21
+ 9. [Component catalog](components/index.md): the full index of the public components.
22
+
23
+ ## Rules for AI
24
+
25
+ - **Start with `llms.txt`** at the package root. It is an index of all Reference pages, with a description of
26
+ each one. A script builds it from `docs/`, so it cannot fall behind them.
27
+ - Import only the public entry points of the package (the list is in the [glossary](glossary.md)). Do not
28
+ import files from the package's `src/` directly.
29
+ - Before you read a page's API, read "When to use" and "When not to use". Components that look alike can
30
+ express different actions.
31
+ - Do not replace a semantic component with hand-written markup if the package already provides a suitable
32
+ public export.
33
+ - Follow the controlled and uncontrolled contract described in the Reference, and the requirements for the
34
+ label (`label`), focus and Escape. A look in a screenshot does not replace these contracts.
35
+ - Document a change to the public API in the same change as the code. The full maintenance rules are in the
36
+ `CLAUDE.md` of the kit's repository. That file does not ship in the package, and there is no link to it here
37
+ on purpose.
38
+
39
+ ## Scope
40
+
41
+ The documents live in the package repository. **Since 3.8.0 they ship with the package** to the registry: the
42
+ whole `docs/` folder and the `llms.txt` index at the package root (ADR-0044). An agent in someone else's
43
+ repository no longer needs a link to that repository or access to it. The Reference is in
44
+ `node_modules/@olddevs/ui/docs/`, in the version that is installed, not the version that is on `main` now.
45
+
46
+ The kit has a public documentation site, but the index does not link to it. The index has no `https://…`
47
+ links. All its paths are relative and point inside the package.
48
+
49
+ **What the package does not include is the ADRs.** Reference pages refer to decisions by number, `ADR-NNNN`,
50
+ many times. But the decisions are kept apart from the code and are not in the package. This does not stop the
51
+ Reference from being complete: the contract, the API and accessibility are described on the pages themselves.
52
+ "Why it was decided this way" stays in the decision records. The trade-off was made on purpose (ADR-0044). If
53
+ you need the reasoning, ask in the repository's issues.
package/llms.txt CHANGED
@@ -127,6 +127,7 @@
127
127
  - [SortableList](docs/components/content/sortable-list.md): Список, порядок которого задаёт пользователь перетаскиванием.
128
128
  - [EditableList](docs/components/content/editable-list.md): Список, в котором строки правят по месту и переставляют перетаскиванием, а новые добавляют снизу.
129
129
  - [RichTextView](docs/components/content/rich-text-view.md): `RichTextView` — показ сохранённого HTML `RichTextEditor` с той же типографикой, что внутри Редактора.
130
+ - [RichTextToc](docs/components/content/rich-text-toc.md): `RichTextToc` — Оглавление Документа рядом с Просмотром (`RichTextView`) или Редактором в `readOnly`.
130
131
  - [VirtualGrid](docs/components/content/virtual-grid.md): Сетка карточек с виртуализацией: в DOM живут видимые ячейки и небольшой запас вокруг.
131
132
  - [Avatar и AvatarGroup](docs/components/content/avatar.md): `Avatar` показывает фотографию по `src` или, если её нет или она не загрузилась, инициалы и стабильный градиент, вычисленные из имени.
132
133
  - [Data display: `Badge`, `Stat`, `DescriptionList`, `Table`](docs/components/content/data-display.md): Выбирайте компонент по форме и смыслу данных: `Badge` отвечает на «сколько» или «есть ли новое», `Stat` — на один показатель с контекстом, `DescriptionList` — на пары «свойство — значение», `Table` —
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@olddevs/ui",
3
- "version": "4.3.0",
3
+ "version": "4.5.0",
4
4
  "description": "Olddevs UI — design system: tokens, themes and accessible UI primitives",
5
5
  "license": "MIT",
6
6
  "private": false,