@olddevs/ui 4.3.0 → 4.4.0

package/docs/api/messages.md

@@ -403,6 +403,7 @@
 | `blockMoveDown`                       | строка  | Move down                                                                        | Вниз                                                                               |
 | `blockDuplicate`                      | строка  | Duplicate                                                                        | Дублировать                                                                        |
 | `blockDelete`                         | строка  | Delete                                                                           | Удалить                                                                            |
+| `toc`                                 | строка  | Table of contents                                                                | Оглавление                                                                         |
 
 ## `errorState`
 

package/docs/api/utilities.en.md

@@ -0,0 +1,233 @@
+---
+category: api
+status: stable
+source: src/index.ts
+sourceHash: 255c163bdc7a
+---
+
+# Shared API: utilities, tokens, constants and types
+
+## Summary for AI
+
+`@olddevs/ui` exports several programmatic APIs besides components. They are meant for integration with the
+components and the shared visual vocabulary. Do not import the internal `src/lib/*` files directly. All public
+component exports and their prop types are documented on the pages of the components themselves. The
+`@olddevs/ui/icons` export is documented in [icons.md](../icons.md).
+
+## When to use
+
+- `cn`: to merge Tailwind classes, especially when `text-caption` and a text color from the kit's scale appear
+  together.
+- `useScrollLock`: for your own controlled overlay composition, when it owns the open state and must lock the
+  `body` scroll.
+- `useMediaQuery`: when the window width decides what is rendered or how it behaves (what to mount, how many
+  months to show, whether to collapse `SplitPanel`), not only the look. To show or hide a block by width, use
+  a Tailwind class. Details are in [SplitPanel](../components/app-shell/split-panel.md).
+- `Size`, `Tone`, `Variant`, `TONE_TOKENS` and `variantClasses`: when you create a new design-system primitive
+  with the same semantic axes.
+- Period helpers: for a relative period in the URL and its conversion to dates. Time helpers: for `HH:MM` input
+  in date and time controls.
+- The theme registry: for a theme switcher and for applying the saved theme early. Take the axis lists from
+  there. Do not rewrite them as constants in your own code.
+
+## When not to use
+
+- Do not create a second `body` scroll-lock counter in the app. Unrelated counters break nested overlays. Use
+  the one `useScrollLock` from the package.
+- Do not build Tailwind classes dynamically, for example `text-${tone}`. Use literal tokens or
+  `variantClasses`. Class names built at runtime do not make it into the CSS build.
+- Do not pass an invalid string from the URL straight to `resolvePeriod`. First narrow it with
+  `isRelativePeriod`.
+- Do not use `maskTime` as the final validation. The mask works during input, and normalization works after it.
+
+## Shared variants
+
+The source of the shared exports is `src/index.ts`. Their implementations are in `src/lib/cn.ts`,
+`src/hooks/useScrollLock.ts`, `src/hooks/useMediaQuery.ts`, `src/lib/variants.ts`, `src/lib/period.ts` and
+`src/lib/time.ts`.
+
+| Export                               | Purpose                                                                                                                                                                    |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cn(...inputs)`                      | `clsx` plus a configured Tailwind merge. The last conflicting class wins, and `text-caption` does not conflict with `text-fg-*`.                                           |
+| `useScrollLock(isLocked)`            | Locks the scroll of `body`, compensates for the scrollbar width and counts nested locks at the module level. Releases the lock on unmount.                                 |
+| `useMediaQuery(query, serverValue?)` | Returns whether the media query matches now, and re-renders the component when it changes. Before hydration, and without `matchMedia`, it returns `serverValue` (`false`). |
+| `Size`                               | The shared scale `sm \| md \| lg`. A specific component may support a subset of it.                                                                                        |
+| `Tone`                               | The semantic color `neutral \| accent \| success \| warning \| danger`, not a shade name.                                                                                  |
+| `Variant`                            | The visual treatment `solid \| soft \| outline \| ghost`.                                                                                                                  |
+| `Numeric`                            | The digit style: `tabular` gives digits of equal width. An axis of the `Text` and `Heading` components, not a separate utility.                                            |
+| `ToneAtoms`                          | The type of a set of ready Tailwind classes for one `Tone`.                                                                                                                |
+| `TONE_TOKENS`                        | The map `Tone → ToneAtoms`. Use it instead of copying token strings.                                                                                                       |
+| `variantClasses(variant, tone)`      | Ready classes for a variant and tone pair, for your own primitive.                                                                                                         |
+| `INVALID_BORDER_CLASS`               | The ready class for the border of an invalid field.                                                                                                                        |
+
+## Periods
+
+| Export                                     | Purpose and limits                                                                                                                                                                                        |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `RELATIVE_PERIODS`, `RelativePeriod`       | The allowed relative values: `7d`, `30d`, `90d`, `180d`, `365d`, `thisMonth`, `lastMonth`, `thisYear`.                                                                                                    |
+| `isRelativePeriod(value)`                  | A runtime type guard for an external string, including one from the URL.                                                                                                                                  |
+| `resolvePeriod(period, timeZone?, now?)`   | Returns the inclusive ISO bounds of a `DateRange`. Uses the local time zone by default. `now` is needed mainly for deterministic tests.                                                                   |
+| `DateRange`                                | A pair `{ start, end }` in ISO `YYYY-MM-DD`. Both bounds are inclusive.                                                                                                                                   |
+| `periodLength(range)`                      | The number of days, inclusive, computed in UTC. A range that was reversed by hand gives at least one day. An unparseable bound gives `0`, which means "nothing to count".                                 |
+| `formatPeriodLength(range, messages?)`     | The label for the period length, from the message catalog: `14 дней` or `14 days`. Without `messages`, the English fallback is used. With an unparseable bound, it returns an empty string, not `0 дней`. |
+| `PeriodPreset`, `periodPresets(messages?)` | A type and a function that builds a short set of standard presets for the UI, with labels from the message catalog. Without `messages`, the labels are in English.                                        |
+| `DEFAULT_PERIOD_PRESETS`                   | `@deprecated` since 2.0.0: an immutable set of presets with English labels. It does not know the locale. Use `periodPresets(messages)`. It is removed in the next major version.                          |
+
+```ts
+const rawPeriod = searchParams.get("period");
+const period = rawPeriod && isRelativePeriod(rawPeriod) ? rawPeriod : "30d";
+const range = resolvePeriod(period, "Europe/Moscow");
+```
+
+## Time
+
+| Export                            | Purpose                                                                                                                                                               |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `maskTime(value)`                 | Keeps up to four digits and adds `:` after the first two: `2130 → 21:30`. Apply it on every input.                                                                    |
+| `normalizeTime(value, fallback?)` | Takes partial input and returns an `HH:MM` value within valid bounds. Empty input returns `fallback`, which defaults to `00:00`. Apply it when the input is complete. |
+| `formatDate(isoDate, locale?)`    | Formats an ISO day from `DatePicker` for display. Documented together with [DatePicker](../components/date-time/date-picker.md).                                      |
+| `upcomingSlots(step, now)`        | Builds the nearest time slots. Documented together with [TimePicker](../components/date-time/time-picker.md).                                                         |
+
+## Input masks
+
+These are pure functions of the mask engine. They are exported apart from the component, because you may need
+to prepare a value before you send it, or check whether it is filled in, without a field on the screen.
+
+| Export                  | Purpose                                                                              |
+| ----------------------- | ------------------------------------------------------------------------------------ |
+| `formatMask(raw, mask)` | Lays out a raw value over the mask. The tail of the mask is not shown in advance.    |
+| `unmask(display, mask)` | Gets the raw value by position. A literal digit from the mask does not leak into it. |
+| `maskCapacity(mask)`    | How many value characters the mask holds: `+7 (999) 999-99-99` → 10.                 |
+
+Mask tokens: `9` is a digit, `a` is a letter, `*` is a digit or a letter. Anything else is a literal. There is
+no escaping. Details are in [MaskedInput](../components/inputs/masked-input.md).
+
+## Themes
+
+The registry of theme axes and the contract for applying them. The kit has **no** theme switcher component.
+`Segmented` already gives the right shape, and a button depends on the storage and the markup of a specific
+app. The reasoning is in ADR-0020. The ready code for two variants of a switcher is in
+[the recipe in theming.md](../theming.md#переключатель-темы).
+
+| Export                                                | Purpose                                                                                                                        |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `UI_THEMES`, `UI_ACCENTS`, `UI_BRANDS`                | The three theme axes as lists. A test checks them against `styles.css`, so they cannot drift apart silently.                   |
+| `normalizeTheme`, `normalizeAccent`, `normalizeBrand` | Turn any value into a valid one. They accept `unknown`. A typical source is storage.                                           |
+| `applyTheme(root, prefs)`                             | Sets all three axes on the element. If an axis is not passed, it returns to its default instead of keeping the previous value. |
+| `themeInitScript({ storageKey })`                     | A **string** of JS for applying the theme early, before the first render.                                                      |
+| `DEFAULT_THEME_PREFS`                                 | The state in which no overlay is set: `dark` / `blue` / `base`.                                                                |
+
+`base` **removes** `data-brand` instead of writing `data-brand="base"`. There is no CSS block with that name,
+and a leftover attribute would look like a working overlay.
+
+### Applying the theme early
+
+Without early theme application, the user sees a flash of the wrong theme between the first render and
+hydration. The kit returns a **string** and does not run code. The consumer's framework knows where to insert
+it, not the design system.
+
+```jsx
+import Script from "next/script";
+import { themeInitScript } from "@olddevs/ui";
+
+<Script
+  id="theme-init"
+  strategy="beforeInteractive"
+  dangerouslySetInnerHTML={{ __html: themeInitScript({ storageKey: "ui-prefs" }) }}
+/>;
+```
+
+The storage format is a JSON object `{ theme, accent, brand }` under this key. The consumer writes it
+(`applyTheme` does not save anything), and the script reads it. Any field can be missing or hold a wrong value.
+Normalization still runs, and broken JSON does not break the page.
+
+## Table state
+
+`useTableState` describes the shape of the `DataTable` state and the links between its parts. The hook **stores
+nothing outside React** and subscribes to nothing. The kit provides the shape, and the consumer owns it
+(ADR-0023).
+
+| Export          | Purpose                                                                          |
+| --------------- | -------------------------------------------------------------------------------- |
+| `useTableState` | `{ state, set, reset }`. One update function instead of ten handlers. See below. |
+| `TableState`    | Sorting, the page and its size, selection, expansion, filters, columns, density. |
+| `TableFilter`   | An applied filter: `id`, `field`, `value`, and optional `label` and `to`.        |
+
+### Invariants the hook exists to keep
+
+- changing **filters, sorting or the page size resets the page** to the first one. Otherwise the user looks at
+  page four of a result set of ten rows, and reads the empty space as "nothing found";
+- **selection is not reset.** The reverse looks tidier, but it breaks a bulk action exactly when that action is
+  needed most;
+- density and column visibility do **not** touch the page. A filter narrows the result set, not the look;
+- an explicit `page` in the same call cancels the reset. This is how the state is restored from the address,
+  in full and in one go.
+
+The update goes through one function because the invariants must hold no matter what changed. Split into
+separate handlers, they would drift apart.
+
+### Moving to the URL
+
+| Export                 | Purpose                                                                    |
+| ---------------------- | -------------------------------------------------------------------------- |
+| `tableStateToParams`   | State to `URLSearchParams`. Defaults are not written.                      |
+| `tableStateFromParams` | `URLSearchParams` to part of the state. Junk input does not break parsing. |
+| `DEFAULT_TABLE_STATE`  | Defaults, except density: the provider sets it.                            |
+
+The functions are **pure and have no `"use client"`**. URL parsing is needed on the server too, because in
+Next.js the state is restored from `searchParams` before rendering. Applying them to the URL is the app's job.
+Routers differ in how they write parameters (`replace` or `push`, array encoding, `basePath`). A kit that tried
+to guess them would get it wrong silently.
+
+```tsx
+const { state, set } = useTableState(tableStateFromParams(searchParams));
+
+// after a change, write it back the way your router supports
+router.replace(`?${tableStateToParams(state)}`);
+```
+
+**Selection and expansion are not kept in the URL**, although the original spec included selection in the table
+state. There are two reasons. The list of keys has no length limit. And a link with a selection, opened the next
+day, marks records that no longer exist. Selection is session state, not URL state.
+
+The restored state is passed to the hook as a whole, in one `set` call. The invariant "narrowing the result set
+resets the page" is cancelled by an explicit page in the same call. Otherwise a link would always open the first
+page.
+
+### A filter token has its own `id`
+
+A filter has its own `id`, not a pair of "field + value" and not a label. Two filters on one field give tokens
+that look the same, and you cannot tell which of the two to remove. A label, however, is localized and truncated.
+
+The model has no operators on purpose. Without `to`, the token means equality. With `to`, it means the range
+`value…to`, where either bound may be an empty string ("from 50", "up to 100"). The presence of the `to` key
+carries the difference, so check it with `!== undefined` (ADR-0063). `contains` and `in` can be added when they
+are needed. In the URL, `to` is the fifth part of the token. Links with three and four parts are read as before.
+For how to build a range in the UI, see [FilterBar](../components/table/filter-bar.md).
+
+## Constants, classes and public types: where they are documented
+
+These are public exports, but not standalone components. The page of the family they belong to describes them,
+so that AI does not treat a class as a general-purpose API:
+
+| Exports                                                                                                                                       | Documentation                                                 |
+| --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `MENU_PANEL_CLASS`, `MENU_ITEM_CLASS`, `MENU_ITEM_ICON_CLASS`, `MENU_ITEM_SHORTCUT_CLASS`, `MENU_SECTION_LABEL_CLASS`, `MENU_SEPARATOR_CLASS` | [Menu](../components/overlays/menu.md)                        |
+| `NAV_BUTTON_CLASS`, `WEEKDAY_CELL_CLASS`                                                                                                      | [Calendar](../components/date-time/calendar.md)               |
+| `pageRange`                                                                                                                                   | [Pagination](../components/navigation/pagination.md)          |
+| `maskTime`, `normalizeTime`                                                                                                                   | [DateTimePicker](../components/date-time/date-time-picker.md) |
+| `formatDate`                                                                                                                                  | [DatePicker](../components/date-time/date-picker.md)          |
+| `upcomingSlots`                                                                                                                               | [TimePicker](../components/date-time/time-picker.md)          |
+
+Each `*Props` type and each component-specific type exported with a component (for example `TableProps`,
+`CommandItem`, `SelectItem`, `KeyboardSelection` or `DrawerSide`) stays part of that component's public API. It
+is described on the page of its family. The [component catalog](../components/index.md) links the public exports
+to the family pages. `src/index.ts` is the final source for all exports.
+
+## Related sources and checks
+
+- Public surface: `src/index.ts`.
+- Implementations: `src/lib/cn.ts`, `src/hooks/useScrollLock.ts`, `src/hooks/useMediaQuery.ts`,
+  `src/lib/variants.ts`, `src/lib/period.ts`, `src/lib/time.ts`, `src/lib/themes.ts`, `src/lib/table-state.ts`,
+  `src/hooks/useTableState.ts`.
+- `maskTime` and `normalizeTime` are also used in `src/components/date-time/DateTimePicker.tsx`.

package/docs/components/content/rich-text-toc.en.md

@@ -0,0 +1,130 @@
+---
+component: RichTextToc
+exports: [RichTextToc, RichTextTocProps]
+category: content
+status: stable
+source: src/editor/features/toc/RichTextToc.tsx
+story: src/editor/features/toc/RichTextToc.stories.tsx
+sourceHash: 5eed0e4804e0
+---
+
+# RichTextToc
+
+## Summary for AI
+
+`RichTextToc` is the Table of contents of a Document, placed next to the View (`RichTextView`) or an Editor in `readOnly`. Collapsed, it is a strip of strokes, one per heading, with the stroke of the current section highlighted. Hovering the strip expands a list of headings; clicking an item scrolls to the heading and moves focus to it. The component is client-side and opt-in: the screen puts it in its own column and passes `target`, a ref to the View or to the Editor's Handle. Headings are read from the target's DOM; the Document has no anchors or `id` attributes, and the page address does not change. It lives in the `@olddevs/ui/editor` entry point. Decision: ADR-0066.
+
+```tsx
+import { RichTextToc, RichTextView } from "@olddevs/ui/editor";
+```
+
+## When to use
+
+- A long Document in the View: an article, a policy, a description, where the reader needs to jump to a section without scrolling through the whole page.
+- An Editor in `readOnly` shows the same long Document and needs the same navigation.
+
+## When not to use
+
+- A short Document: with fewer than two headings the component renders nothing, and on three or four paragraphs a Table of contents only takes up space.
+- Navigation between application pages or sections of a site: use `SideNav` or `Tabs`, not the Table of contents of a Document.
+- A link to a section that can be shared: the Table of contents goes to a heading without an anchor (`#slug`), and the page address does not change. A link to a section would need its own ADR about `id` in the Schema.
+- A Table of contents as part of the Document itself, a Block inside the text: the Schema has no such Block.
+- The Table of contents belongs inside the Editor field and the screen has no column for it: use the Editor's `toc` Tool, the same strip in the left gutter of the frame, sticky under the Toolbar and in a field with `maxHeight` (the `RichTextEditor` page, "Table of contents" section).
+
+## Minimal example
+
+```tsx
+"use client";
+import { RichTextToc, RichTextView } from "@olddevs/ui/editor";
+import { useRef } from "react";
+
+export function Article({ html }: { html: string }) {
+  const view = useRef<HTMLDivElement>(null);
+  return (
+    <div className="flex items-start gap-6">
+      {/* The screen sets the column and the stickiness, not the component. */}
+      <div className="sticky top-[calc(var(--topbar-h,0px)+16px)] w-10 shrink-0">
+        <RichTextToc target={view} />
+      </div>
+      <RichTextView ref={view} html={html} className="min-w-0 flex-1" />
+    </div>
+  );
+}
+```
+
+`RichTextView` stays server-safe here: only the screen's wrapper is client-side, because it needs the `ref`.
+
+## Public API
+
+| Prop        | Meaning                                                                                                                                                                                                                                    |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `target`    | Required. A ref to a `RichTextView` or to the Handle of a `RichTextEditor` whose headings the Table of contents shows. Headings are read after mounting, so there is no strip before hydration.                                            |
+| `offsetVar` | The name of the CSS variable with the height of the screen's sticky header, `--topbar-h` by default (`TopBar` publishes it). A jump places the heading below the header, and the highlight counts a section from the header's bottom edge. |
+| `listWidth` | The width of the list: a CSS length or pixels, `240` by default. It is fixed rather than sized to the longest heading; a heading that does not fit is truncated with an ellipsis.                                                          |
+| `className` | Classes for the root. The remaining `div` props go to the root.                                                                                                                                                                            |
+
+### Which headings are included
+
+- `h1`–`h4` at the top level of the Document and inside a Wrapper.
+- Headings in the columns of a Layout are not included: two headings at the same height in neighboring columns confuse the highlight of the current section. Headings inside custom Blocks and their Islands are not included either: their content is part of the Block, not of the Document's structure.
+- With fewer than two headings the component renders nothing, and the screen's column stays empty.
+
+The indent of an item and the length of its stroke depend on the level **relative to the largest heading in the Document**: if the Document starts with `h2`, then `h2` has no indent and the longest stroke. The deeper the level, the shorter the stroke.
+
+### A live Document
+
+The list follows the target: a new `html` of the View, a new value of the Editor or an edit rebuilds it through a `MutationObserver` with a short delay. When a second heading appears, the strip appears; when one goes, it disappears. The Editor's Handle provides the Document only once the engine is ready; until then the Table of contents waits and picks it up on its own.
+
+### A long Document
+
+Every heading gets its own stroke. The strip is never taller than the window: when there is not enough room for the strokes, the step between them shrinks. The list has a limited height and scrolls, and the item of the current section stays within its visible part.
+
+### The strip and the list
+
+- The strip is a button labeled "Table of contents" with `aria-expanded`. The stroke of the current section is in the accent color, thicker and slightly longer than the others.
+- The list opens when you hover the strip, after a short delay: a cursor passing by accidentally does not open it. A press, a tap, Enter and Space open it immediately.
+- The list sits to the right of the strip, over the text. Clicking an item goes to the heading, and the list **stays open**. It closes when the cursor leaves the strip and the list, on Escape and on a press outside it.
+- The current section is highlighted both in the strip and in the list (`aria-current="location"`).
+
+### Jumping to a heading
+
+Clicking an item scrolls to the heading (without animation under `prefers-reduced-motion`) and moves focus to it: the next Tab continues from the heading, and a screen reader reads it. While it has focus, the heading gets `tabindex="-1"`; when focus leaves, the attribute is removed, so the Document keeps no trace. The page address does not change, no `id` attributes appear, and the Schema and `sanitizeRichText` stay as they were.
+
+The heading you jump to is briefly highlighted with an accent-colored background that fades out in about a second and a half: the eye finds where the page has scrolled to, even if the heading did not reach the top edge (the end of the Document). The highlight is a Web Animations animation; it writes neither a class nor a `style` into the Document's markup.
+
+The nearest scrollable ancestor of the target scrolls, or the window if there is none.
+
+**An Editor being edited.** If the Editor is switched from `readOnly` to editing, the Table of contents keeps working: the list is rebuilt on edits, and a jump scrolls to the heading and highlights it. Focus does not move to the heading, though, and the caret stays where the author left it: there is no way to focus a heading inside a `contenteditable` without disturbing the caret. This mode is not covered by the contract.
+
+### Sticky header
+
+The component takes the header's height by the contract of ADR-0016: from the CSS variable whose name `offsetVar` carries. If the variable exists, the heading lands exactly below the header, and a section becomes the current one when its heading reaches the header's bottom edge. If it does not, the offset is the heading's `scroll-margin-top`, which the screen can set itself. There is no numeric offset prop: the header's height depends on the breakpoint, and a constant would leave a gap on a narrow screen.
+
+### Narrow screens
+
+If there is no room to the left of the text, the Table of contents hides itself: a strip that overlaps the Document's text or goes past the left edge of the window becomes invisible (`visibility: hidden`) together with its list. It keeps its space in the column, so the screen layout does not jump. When room appears, the strip comes back. This works both for a column next to the text and for the page margin to the left of a centered column (the `Margin` story).
+
+## Accessibility and keyboard
+
+| Key          | Where | Action                                                   |
+| ------------ | ----- | -------------------------------------------------------- |
+| Enter, Space | strip | Open the list, focus moves to the current section's item |
+| ↓ ↑          | list  | Next and previous item                                   |
+| Home, End    | list  | First and last item                                      |
+| Enter        | item  | Go to the heading, focus moves to the heading            |
+| Escape       | list  | Close the list, focus moves to the strip                 |
+
+The list is a `nav` labeled "Table of contents", and its items are buttons in a `ul` list. The list is an overlay in the Escape stack: nested in another overlay, it closes first. Hover and focus do not take focus away from where it is: the list complements the strip rather than taking over control. Labels come from the kit's message catalog (`editor.toc`): "Оглавление" in `ru`, "Table of contents" in the fallback.
+
+## Anti-patterns
+
+- Pointing `target` at a wrapper that holds the View together with neighboring blocks of the page: other headings end up in the Table of contents. Put the ref on the View itself.
+- Hiding the Table of contents on a narrow screen with `display: none` on the column while also relying on its self-hiding: self-hiding is for when the column stays but has no room. A column that should not exist on a phone is removed by the screen itself.
+- Adding `id` to headings for the sake of the Table of contents: it does not need them, and the Schema will strip them.
+
+## Related sources and Storybook
+
+- Source: `src/editor/features/toc/RichTextToc.tsx`; heading collection — `headings.ts` next to it
+- Stories: `src/editor/features/toc/RichTextToc.stories.tsx`
+- Tests: `tests/rich-text-toc.test.tsx`; in the browser — `tests-visual/interactions.spec.ts`, the `RichTextToc` block
+- Decision: ADR-0066 "The Table of contents of a Document as a separate `RichTextToc` component"

package/docs/components/content/rich-text-toc.md

@@ -0,0 +1,129 @@
+---
+component: RichTextToc
+exports: [RichTextToc, RichTextTocProps]
+category: content
+status: stable
+source: src/editor/features/toc/RichTextToc.tsx
+story: src/editor/features/toc/RichTextToc.stories.tsx
+---
+
+# RichTextToc
+
+## Кратко для AI
+
+`RichTextToc` — Оглавление Документа рядом с Просмотром (`RichTextView`) или Редактором в `readOnly`. Свёрнуто — полоса штрихов, по одному на заголовок, штрих текущего раздела подсвечен. Наведение на полосу раскрывает список заголовков, клик по пункту прокручивает к заголовку и ставит на него фокус. Компонент клиентский и подключается только явно: экран ставит его в свою колонку и передаёт `target` — ref на Просмотр или Хэндл Редактора. Заголовки читаются из DOM цели, якорей и `id` в Документе нет, адрес страницы не меняется. Живёт во входе `@olddevs/ui/editor`. Решение — ADR-0066.
+
+```tsx
+import { RichTextToc, RichTextView } from "@olddevs/ui/editor";
+```
+
+## Когда использовать
+
+- Длинный Документ в Просмотре: статья, регламент, описание, где читателю нужно перейти к разделу, не листая страницу целиком.
+- Редактор в `readOnly` показывает тот же длинный Документ, и навигация нужна там же.
+
+## Когда не использовать
+
+- Короткий Документ: если в нём меньше двух заголовков, компонент ничего не рисует, а на трёх-четырёх абзацах Оглавление только занимает место.
+- Навигация по страницам приложения или разделам сайта — это `SideNav` или `Tabs`, а не Оглавление Документа.
+- Ссылка на раздел, которой можно поделиться: Оглавление ведёт к заголовку без якоря (`#slug`), адрес страницы не меняется. Ссылка на раздел потребует отдельного ADR об `id` в Схеме.
+- Оглавление как часть самого Документа, Блоком внутри текста: такого Блока в Схеме нет.
+- Оглавление нужно внутри поля Редактора, а своей колонки у экрана нет — это Инструмент `toc` Редактора: та же полоса в левом поле рамки, липкая под Панелью и в поле с `maxHeight` (страница `RichTextEditor`, раздел «Оглавление»).
+
+## Минимальный пример
+
+```tsx
+"use client";
+import { RichTextToc, RichTextView } from "@olddevs/ui/editor";
+import { useRef } from "react";
+
+export function Article({ html }: { html: string }) {
+  const view = useRef<HTMLDivElement>(null);
+  return (
+    <div className="flex items-start gap-6">
+      {/* Колонку и липкость задаёт экран, а не компонент. */}
+      <div className="sticky top-[calc(var(--topbar-h,0px)+16px)] w-10 shrink-0">
+        <RichTextToc target={view} />
+      </div>
+      <RichTextView ref={view} html={html} className="min-w-0 flex-1" />
+    </div>
+  );
+}
+```
+
+`RichTextView` при этом остаётся серверно-безопасным: клиентская здесь только обёртка экрана, которой нужен `ref`.
+
+## Public API
+
+| Prop        | Значение                                                                                                                                                                              |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `target`    | Обязательный. Ref на `RichTextView` или на Хэндл `RichTextEditor`, чьи заголовки показывает Оглавление. Заголовки читаются после монтирования: до гидратации полосы нет.              |
+| `offsetVar` | Имя CSS-переменной с высотой липкой шапки экрана, по умолчанию `--topbar-h` (её публикует `TopBar`). Переход ставит заголовок под шапку, подсветка считает раздел от её нижнего края. |
+| `listWidth` | Ширина списка: длина CSS или пиксели, по умолчанию `240`. Постоянная, а не по самому длинному заголовку; заголовок, что не помещается, обрезается многоточием.                        |
+| `className` | Классы корня. Остальные свойства `div` уходят на корень.                                                                                                                              |
+
+### Какие заголовки попадают
+
+- `h1`–`h4` на верхнем уровне Документа и внутри Обёртки.
+- Не попадают заголовки в колонках Раскладки: два заголовка на одной высоте в соседних колонках путают подсветку текущего раздела. Не попадают и заголовки внутри своих Блоков и их Островов: их содержимое — часть Блока, а не структура Документа.
+- Меньше двух заголовков — компонент ничего не рисует, колонка экрана остаётся пустой.
+
+Отступ пункта и длина штриха считаются по уровню **относительно самого крупного заголовка в Документе**: если Документ начинается с `h2`, у `h2` нет отступа и самый длинный штрих. Чем глубже уровень, тем короче штрих.
+
+### Живой Документ
+
+Список следит за целью: новый `html` Просмотра, новое значение Редактора или правка пересобирают его через `MutationObserver` с короткой задержкой. Пришёл второй заголовок — полоса появляется, ушёл — пропадает. Хэндл Редактора даёт Документ, только когда движок готов: до этого Оглавление ждёт и подхватывает его само.
+
+### Длинный Документ
+
+На каждый заголовок свой штрих. Полоса не выше окна: когда штрихам не хватает места, шаг между ними сжимается. Список ограничен по высоте и прокручивается, пункт текущего раздела держится в его видимой части.
+
+### Полоса и список
+
+- Полоса — кнопка с подписью «Оглавление» и `aria-expanded`. Штрих текущего раздела — цветом акцента, толще и чуть длиннее остальных.
+- Список открывается наведением на полосу с короткой задержкой: случайный пролёт курсора его не открывает. Нажатие, касание, Enter и Space открывают его сразу.
+- Список стоит справа от полосы поверх текста. Клик по пункту ведёт к заголовку, а список **остаётся открытым**: закрывается он, когда курсор ушёл с полосы и списка, по Escape и по нажатию вне него.
+- Текущий раздел подсвечен и в полосе, и в списке (`aria-current="location"`).
+
+### Переход
+
+Клик по пункту прокручивает к заголовку (при `prefers-reduced-motion` — без анимации) и ставит на него фокус: следующий Tab идёт от заголовка, скринридер читает его. На время фокуса заголовок получает `tabindex="-1"`, с уходом фокуса атрибут снимается — в Документе следа не остаётся. Адрес страницы не меняется, `id` не появляются, Схема и `sanitizeRichText` прежние.
+
+Заголовок, к которому перешли, ненадолго подсвечивается фоном цвета акцента, и фон гаснет примерно за полторы секунды: глаз находит, куда приехала страница, даже если заголовок не встал к верхнему краю (конец Документа). Подсветка — анимация Web Animations, в разметку Документа она не пишет ни класса, ни `style`.
+
+Прокручивается ближайший прокручиваемый предок цели, а если его нет — окно.
+
+**Редактор в правке.** Если Редактор перевели из `readOnly` в правку, Оглавление продолжает работать: список пересобирается на правках, переход прокручивает к заголовку и подсвечивает его. Фокус при этом на заголовок не переходит, а каретка остаётся там, где её оставил автор: поставить фокус на заголовок внутри `contenteditable`, не тронув каретку, нельзя. Контрактом этот режим не обещан.
+
+### Липкая шапка
+
+Высоту шапки компонент берёт по контракту ADR-0016: из CSS-переменной, имя которой передаёт `offsetVar`. Переменная есть — заголовок встаёт ровно под шапку, и текущим раздел становится, когда его заголовок дошёл до её нижнего края. Переменной нет — отступом служит `scroll-margin-top` заголовка, который экран может задать сам. Числового пропа отступа нет: высота шапки зависит от брейкпоинта, и константа оставила бы просвет на узком экране.
+
+### Узкий экран
+
+Если слева от текста нет места, Оглавление прячется само: полоса, которая заходит на текст Документа или уходит за левый край окна, становится невидимой (`visibility: hidden`) вместе со своим списком. Место в колонке она сохраняет, раскладка экрана не прыгает. Когда место появляется, полоса возвращается. Так работает и колонка рядом с текстом, и поле страницы слева от центрированной колонки (история `Margin`).
+
+## Доступность и клавиатура
+
+| Клавиша      | Где    | Действие                                          |
+| ------------ | ------ | ------------------------------------------------- |
+| Enter, Space | полоса | Открыть список, фокус — на пункт текущего раздела |
+| ↓ ↑          | список | Следующий и предыдущий пункт                      |
+| Home, End    | список | Первый и последний пункт                          |
+| Enter        | пункт  | Перейти к заголовку, фокус — на заголовок         |
+| Escape       | список | Закрыть список, фокус — на полосу                 |
+
+Список — `nav` с подписью «Оглавление», пункты — кнопки в списке `ul`. Список — Оверлей в Стеке Escape: вложенный в другой оверлей, он закрывается первым. Наведение и фокус не уводят фокус с места: список дополняет полосу, а не забирает управление. Подписи берутся из каталога сообщений кита (`editor.toc`): «Оглавление» в `ru`, «Table of contents» в фолбэке.
+
+## Антипаттерны
+
+- Передавать `target` на обёртку вокруг Просмотра вместе с соседними блоками страницы: в Оглавление попадут чужие заголовки. Ref — на сам Просмотр.
+- Прятать Оглавление на узком экране через `display: none` у колонки и одновременно рассчитывать на его самоскрытие: самоскрытие нужно, когда колонка остаётся, а места в ней нет. Колонку, которой нет на телефоне, экран убирает сам.
+- Ставить `id` заголовкам ради Оглавления: оно в них не нуждается, а Схема их снимет.
+
+## Связанные исходники и Storybook
+
+- Исходник: `src/editor/features/toc/RichTextToc.tsx`, сбор заголовков — `headings.ts` рядом
+- Stories: `src/editor/features/toc/RichTextToc.stories.tsx`
+- Тесты: `tests/rich-text-toc.test.tsx`; в браузере — `tests-visual/interactions.spec.ts`, блок `RichTextToc`
+- Решение: ADR-0066 «Оглавление Документа отдельным компонентом `RichTextToc`»

package/docs/components/index.en.md

@@ -1,5 +1,5 @@
 ---
-sourceHash: 8b34aab7b3be
+sourceHash: 1efca315c26c
 ---
 
 # Component catalog
@@ -141,6 +141,7 @@ Components built from primitives: the page frame, its navigation and header.
 - [SortableList](content/sortable-list.md): `SortableList` — a short list the user reorders by dragging: menu sections, scenario steps, priorities; lists sharing a `group` can exchange rows, which is how a kanban board is built
 - [EditableList](content/editable-list.md): `EditableList` — a list whose rows can be edited in place and reordered by dragging, and which can be added to at the bottom: a checklist, tasks; if you only need the order, `SortableList` is enough
 - [RichTextView](content/rich-text-view.md): `RichTextView` — displays ready-made rich text from the Editor without the Editor itself; a separate entry point `@olddevs/ui/editor`, suitable for a server component
+- [RichTextToc](content/rich-text-toc.md): `RichTextToc` — the table of contents of a long Document next to the View or a `readOnly` Editor: a strip of strokes at the edge of the text, a list of headings on hover, a click goes to the heading; the `@olddevs/ui/editor` entry point
 - [VirtualGrid](content/virtual-grid.md): `VirtualGrid` — a grid of hundreds or thousands of previews that renders only the visible cells and lets you select them; for a dozen cards `Grid` is enough
 - [Avatar](content/avatar.md): `Avatar`, `AvatarGroup` — a round image of a person: a photo or, if there is none, initials; `AvatarGroup` shows several participants with a "+N" overflow count
 - [Data display](content/data-display.md): `Badge`, `Stat`, `DescriptionList`, `Table` — four ways to show data: a counter or a label, a key metric with an explanation, "property and value" pairs, a table of records of the same kind

package/docs/components/index.md

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