@olddevs/ui 4.3.0 → 4.4.0

package/docs/index.en.md

@@ -0,0 +1,53 @@
+---
+sourceHash: 7fafe8d11f89
+---
+
+# `@olddevs/ui` Reference
+
+This Reference is the contract for developers and AI agents who use the package's public API. The source of
+truth for the exports is [`src/index.ts`](../src/index.ts). Component sources, tests and Storybook confirm the
+behavior claims on the pages.
+
+## Start here
+
+1. [Install the package](getting-started.md): imports, CSS and Tailwind 4.
+2. [Choose a component](component-selection.md): pick the meaning first, not a similar look.
+3. [Shared conventions](conventions.md): the prop vocabulary, controlled state and the limits of the public API.
+4. [Glossary](glossary.md): the terms of the kit and the Editor, and what not to confuse them with.
+5. [Accessibility](accessibility.md): the required rules for names, focus and the keyboard.
+6. [Themes, tokens and brands](theming.md): the four token layers and how to add your own brand in one CSS block.
+7. [Palette](palette.md): the palette primitive values and the roles by theme, in one table.
+8. [Localization](i18n.md): the provider, the message catalog and how to connect to the consumer's `I18nProvider`.
+9. [Component catalog](components/index.md): the full index of the public components.
+
+## Rules for AI
+
+- **Start with `llms.txt`** at the package root. It is an index of all Reference pages, with a description of
+  each one. A script builds it from `docs/`, so it cannot fall behind them.
+- Import only the public entry points of the package (the list is in the [glossary](glossary.md)). Do not
+  import files from the package's `src/` directly.
+- Before you read a page's API, read "When to use" and "When not to use". Components that look alike can
+  express different actions.
+- Do not replace a semantic component with hand-written markup if the package already provides a suitable
+  public export.
+- Follow the controlled and uncontrolled contract described in the Reference, and the requirements for the
+  label (`label`), focus and Escape. A look in a screenshot does not replace these contracts.
+- Document a change to the public API in the same change as the code. The full maintenance rules are in the
+  `CLAUDE.md` of the kit's repository. That file does not ship in the package, and there is no link to it here
+  on purpose.
+
+## Scope
+
+The documents live in the package repository. **Since 3.8.0 they ship with the package** to the registry: the
+whole `docs/` folder and the `llms.txt` index at the package root (ADR-0044). An agent in someone else's
+repository no longer needs a link to that repository or access to it. The Reference is in
+`node_modules/@olddevs/ui/docs/`, in the version that is installed, not the version that is on `main` now.
+
+The kit has a public documentation site, but the index does not link to it. The index has no `https://…`
+links. All its paths are relative and point inside the package.
+
+**What the package does not include is the ADRs.** Reference pages refer to decisions by number, `ADR-NNNN`,
+many times. But the decisions are kept apart from the code and are not in the package. This does not stop the
+Reference from being complete: the contract, the API and accessibility are described on the pages themselves.
+"Why it was decided this way" stays in the decision records. The trade-off was made on purpose (ADR-0044). If
+you need the reasoning, ask in the repository's issues.

package/llms.txt

@@ -127,6 +127,7 @@
 - [SortableList](docs/components/content/sortable-list.md): Список, порядок которого задаёт пользователь перетаскиванием.
 - [EditableList](docs/components/content/editable-list.md): Список, в котором строки правят по месту и переставляют перетаскиванием, а новые добавляют снизу.
 - [RichTextView](docs/components/content/rich-text-view.md): `RichTextView` — показ сохранённого HTML `RichTextEditor` с той же типографикой, что внутри Редактора.
+- [RichTextToc](docs/components/content/rich-text-toc.md): `RichTextToc` — Оглавление Документа рядом с Просмотром (`RichTextView`) или Редактором в `readOnly`.
 - [VirtualGrid](docs/components/content/virtual-grid.md): Сетка карточек с виртуализацией: в DOM живут видимые ячейки и небольшой запас вокруг.
 - [Avatar и AvatarGroup](docs/components/content/avatar.md): `Avatar` показывает фотографию по `src` или, если её нет или она не загрузилась, инициалы и стабильный градиент, вычисленные из имени.
 - [Data display: `Badge`, `Stat`, `DescriptionList`, `Table`](docs/components/content/data-display.md): Выбирайте компонент по форме и смыслу данных: `Badge` отвечает на «сколько» или «есть ли новое», `Stat` — на один показатель с контекстом, `DescriptionList` — на пары «свойство — значение», `Table` — 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olddevs/ui",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Olddevs UI — design system: tokens, themes and accessible UI primitives",
   "license": "MIT",
   "private": false,

package/src/editor/RichTextEditor.tsx

@@ -16,6 +16,7 @@ import {
   useId,
   useImperativeHandle,
   useLayoutEffect,
+  useCallback,
   useMemo,
   useRef,
   useState,
@@ -58,6 +59,7 @@ import type { ToolPopoverRequest } from "./core/toolButtons.js";
 import type { TextCardControl } from "./ui/TextCard.js";
 import { SelectionPopover } from "./ui/ToolButtonView.js";
 import { tableChunk } from "./features/table/tableTool.js";
+import { stickyOffset } from "./features/toc/stickyOffset.js";
 import { replaceWithMarkdown } from "./core/markdown.js";
 import {
   documentFromJSON,
@@ -107,6 +109,15 @@ const TextCard = lazy(() =>
  * `basic`, который меряется бюджетом «старта». Плагин подсветки и сочетания
  * маленькие и стоят в движке сразу.
  */
+/*
+  Ядро Оглавления (Инструмент `toc`) — ленивым чанком: его включают единицы, а
+  полоса со списком и `HoverCard` стоили бы каждому Редактору ~5 kB gzip на
+  старте. Чанк приходит, только когда Инструмент включён и движок готов.
+*/
+const TocCore = lazy(() =>
+  import("./features/toc/RichTextToc.js").then((module) => ({ default: module.TocCore }))
+);
+
 const SearchPanel = lazy(() =>
   import("./features/search/SearchPanel.js").then((module) => ({ default: module.SearchPanel }))
 );
@@ -994,6 +1005,52 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
           }
         : { maxHeight: areaLength };
 
+    /*
+      Оглавление в левом поле (Инструмент `toc`, ADR-0068). Полоса липнет под
+      фиксированной Панелью: её высота меряется, потому что Панель переносит
+      ряд кнопок на узком поле. В прокручиваемом поле край — верх области.
+    */
+    const tocOn = enabledTools.has("toc");
+    const [toolbarShell, setToolbarShell] = useState<HTMLDivElement | null>(null);
+    const [toolbarHeight, setToolbarHeight] = useState(0);
+    useEffect(() => {
+      if (!toolbarShell || typeof ResizeObserver === "undefined") {
+        setToolbarHeight(toolbarShell?.offsetHeight ?? 0);
+        return;
+      }
+      const observer = new ResizeObserver(() => setToolbarHeight(toolbarShell.offsetHeight));
+      observer.observe(toolbarShell);
+      return () => observer.disconnect();
+    }, [toolbarShell]);
+    /*
+      Нижний край липкого верха поля: шапка приложения и Панель над Документом.
+      Не `null` никогда, даже без шапки: иначе переход ушёл бы в `scrollIntoView`,
+      а тот двигает и страницу вокруг поля с `maxHeight`. В прокручиваемом поле
+      подсветка и переход считают от верха области и этот край не используют.
+    */
+    const tocStickyTop = useCallback(
+      () => (stickyOffset("--topbar-h") ?? 0) + toolbarHeight,
+      [toolbarHeight]
+    );
+    /*
+      Переход в правке ставит каретку в конец заголовка, как структура документа
+      в Google Docs: с ним можно сразу писать. Прокрутку делает Оглавление, а
+      движок не прокручивает, чтобы не спорить с ним.
+      В `readOnly` каретки нет — фокус на заголовок ставит само Оглавление.
+    */
+    const tocFocusHeading = useCallback((heading: HTMLElement) => {
+      const current = editorRef.current;
+      if (!current || current.isDestroyed || !current.isEditable) return false;
+      const inside = current.view.posAtDOM(heading, 0);
+      const end = inside + current.state.doc.resolve(inside).parent.content.size;
+      current.commands.setTextSelection(end);
+      // `view.focus()`, а не команда `focus`: та ставит фокус кадром позже, и
+      // пункт списка, отпускающий фокус после клика, отдал бы его странице.
+      // ProseMirror фокусирует без прокрутки — прокрутку делает Оглавление.
+      current.view.focus();
+      return true;
+    }, []);
+
     /*
       `Alt+F10` — фокус на первое доступное действие Панели. Плавающую Панель
       клавиша показывает сама, не дожидаясь задержки показа: человек с
@@ -1395,6 +1452,15 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
     const leaveTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
     useEffect(() => () => clearTimeout(leaveTimerRef.current), []);
 
+    /** Цель Оглавления — Документ движка; объект новый с каждым движком. */
+    const tocTarget = useMemo(
+      () => ({
+        get current() {
+          return editor && !editor.isDestroyed ? (editor.view.dom as HTMLElement) : null;
+        },
+      }),
+      [editor]
+    );
     const searchPanelElement = (className: string) =>
       editor &&
       searchPanel && (
@@ -1450,7 +1516,7 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
               `z-[1]` — внутри поля, а не ступень стека слоёв: Панель не
               оверлей и должна оставаться ниже любого из них.
             */
-            <div className={TOOLBAR_SHELL_CLASS}>
+            <div ref={setToolbarShell} className={TOOLBAR_SHELL_CLASS}>
               <EditorToolbar
                 editor={editor}
                 tools={enabledTools}
@@ -1511,7 +1577,37 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
             style={areaStyle}
           >
             {/* В HTML-режиме Документ скрыт, но смонтирован: движок и история живы. */}
-            <EditorContent editor={editor} hidden={sourceOpen} />
+            {tocOn ? (
+              /*
+                Левое поле Оглавления: колонка есть, только пока есть полоса —
+                `TocCore` с меньше чем двумя заголовками не рисует ничего, и
+                текст стоит у края, как без Инструмента (ADR-0068, п. 2).
+              */
+              <div className="flex items-start">
+                {editor && !sourceOpen && (
+                  <Suspense fallback={null}>
+                    <TocCore
+                      target={tocTarget}
+                      stickyTop={tocStickyTop}
+                      focusHeading={tocFocusHeading}
+                      alignToFirstHeading
+                      data-toc-gutter=""
+                      className="sticky mr-3 shrink-0"
+                      style={{
+                        top: scrolls
+                          ? "0.5rem"
+                          : `calc(var(--topbar-h, 0px) + ${toolbarHeight}px + 0.5rem)`,
+                      }}
+                    />
+                  </Suspense>
+                )}
+                <div className="min-w-0 flex-1">
+                  <EditorContent editor={editor} hidden={sourceOpen} />
+                </div>
+              </div>
+            ) : (
+              <EditorContent editor={editor} hidden={sourceOpen} />
+            )}
             {!editor && (
               /*
               Скелет (ADR-0058, п. 11.4): до Готовности и при сбое загрузчика —
@@ -1737,7 +1833,15 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
             ref={hiddenRef}
             type="hidden"
             name={name}
-            defaultValue={initial}
+            /*
+              Значение скрытого поля пишет Редактор (`emit`, эффекты движка), а
+              не React. Но React на КАЖДОМ обновлении заново ставит `defaultValue`,
+              а у `type="hidden"` это и есть его значение: любой рендер родителя
+              откатывал бы поле формы к входящей строке. Поэтому после монтажа в
+              `defaultValue` уходит то, что уже лежит в поле, — React видит равенство
+              и ничего не трогает. Серверный рендер и первый кадр несут `initial`.
+            */
+            defaultValue={hiddenRef.current?.value ?? initial}
             // Выключенное поле не уходит в форму — как нативное. Поле только
             // для чтения уходит: это показанное значение, а не недоступный
             // контрол.

package/src/editor/core/handle.ts

@@ -4,10 +4,11 @@ import { createNodeFromContent, type JSONContent } from "@tiptap/core";
 import { closeHistory } from "@tiptap/pm/history";
 import type { Fragment } from "@tiptap/pm/model";
 import type { Editor } from "@tiptap/react";
-import type { RefObject } from "react";
 import { textBetween } from "./atomText.js";
 import { isRichTextDocument, type RichTextDocument } from "./jsonDocument.js";
 
+export { notifyHandleEditor, watchHandleEditor } from "./handleWatchers.js";
+
 /**
  * Плоские методы Хэндла (ADR-0058, раздел 8): то, что экран делает с Редактором
  * чаще всего. Остальное — `editor` (команды Меток, Блоков и своих Инструментов).
@@ -287,25 +288,3 @@ export function createHandleMethods(host: HandleHost): RichTextEditorHandleMetho
     canRedo: () => available("redo"),
   };
 }
-
-/*
-  Хук-селектор не знает, когда у `ref` появится движок: Редактор создаёт его
-  после первого рендера экрана и перерисовывается сам, а экран — нет. Поэтому
-  подписки живут по самому объекту `ref`, который есть с первого рендера, и
-  Редактор сообщает об смене движка по нему.
-*/
-const watchers = new WeakMap<object, Set<() => void>>();
-
-/** Подписка хука на смену движка у Редактора, привязанного к этому `ref`. */
-export function watchHandleEditor(ref: RefObject<unknown>, listener: () => void): () => void {
-  let set = watchers.get(ref);
-  if (!set) watchers.set(ref, (set = new Set()));
-  set.add(listener);
-  return () => void set.delete(listener);
-}
-
-/** Редактор сообщает: движок у `ref` появился или сменился. */
-export function notifyHandleEditor(ref: unknown): void {
-  if (typeof ref !== "object" || ref === null) return;
-  watchers.get(ref)?.forEach((listener) => listener());
-}

package/src/editor/core/handleWatchers.ts

@@ -0,0 +1,27 @@
+import type { RefObject } from "react";
+
+/*
+  Хук-селектор не знает, когда у `ref` появится движок: Редактор создаёт его
+  после первого рендера экрана и перерисовывается сам, а экран — нет. Поэтому
+  подписки живут по самому объекту `ref`, который есть с первого рендера, и
+  Редактор сообщает об смене движка по нему.
+
+  Модуль вынесен из `handle.ts` и не знает движка: подписаться на смену движка
+  нужно и `RichTextToc`, а ему Tiptap в бандл не нужен.
+*/
+
+const watchers = new WeakMap<object, Set<() => void>>();
+
+/** Подписка хука на смену движка у Редактора, привязанного к этому `ref`. */
+export function watchHandleEditor(ref: RefObject<unknown>, listener: () => void): () => void {
+  let set = watchers.get(ref);
+  if (!set) watchers.set(ref, (set = new Set()));
+  set.add(listener);
+  return () => void set.delete(listener);
+}
+
+/** Редактор сообщает: движок у `ref` появился или сменился. */
+export function notifyHandleEditor(ref: unknown): void {
+  if (typeof ref !== "object" || ref === null) return;
+  watchers.get(ref)?.forEach((listener) => listener());
+}

package/src/editor/core/tools.ts

@@ -50,6 +50,11 @@
  * разметку решает Схема, и режим её не расширяет. В `basic` его нет: в
  * комментарии кнопка «HTML» без явного запроса экрана — лишняя.
  *
+ * `toc` — Оглавление в левом поле рамки (ADR-0068): полоса и список
+ * `RichTextToc`, липкие под Панелью или в прокручиваемом поле. Своей Схемы нет.
+ * В пресеты не входит — ни в `full`, ни в `basic`: оно меняет раскладку поля,
+ * и обновление кита не должно сдвигать текст там, где его не просили.
+ *
  * `search` — поиск и замена по Документу: кнопка «Поиск»
  * фиксированной Панели и `Mod+F` в поле открывают панель в углу поля. Своей
  * Схемы нет, как у `clearFormatting`. Есть и в `basic`: искать по длинному
@@ -85,6 +90,7 @@ export const TOOLS = [
   "source",
   "search",
   "insertMenu",
+  "toc",
 ] as const;
 
 /** Имя инструмента Редактора. Список и смысл каждого — на странице компонента. */
@@ -104,7 +110,8 @@ export type RichTextEditorPreset = "full" | "basic";
  * markdown-шорткатом, чем через меню.
  */
 export const PRESETS: Record<RichTextEditorPreset, readonly Tool[]> = {
-  full: TOOLS,
+  // Все встроенные, кроме Оглавления: его включают только явно (ADR-0068).
+  full: TOOLS.filter((tool) => tool !== "toc"),
   basic: [
     "history",
     "bold",
@@ -122,7 +129,7 @@ export const PRESETS: Record<RichTextEditorPreset, readonly Tool[]> = {
 /**
  * Пресеты наружу — массивами (ADR-0058, п. 1.2): свой набор собирается из них,
  * например `[...RICH_TEXT_PRESETS.full, mergeTagTool]`. Копии заморожены:
- * `PRESETS.full` — это `TOOLS`, и правка массива потребителем меняла бы набор
+ * `PRESETS.full` — почти весь `TOOLS`, и правка массива потребителем меняла бы набор
  * кита во всех Редакторах страницы. Состав пресета — не контракт (ADR-0058,
  * п. 12.5): стабильный набор — точный список имён.
  */