@pgcorp/ui-kit 0.9.0 → 0.10.0

package/docs/rich-document.md

@@ -0,0 +1,216 @@
+# Безопасные rich documents / Safe rich documents
+
+## Назначение / Purpose
+
+`SRichDocument` отображает сериализуемый документ по закрытому контракту
+`SRichDocumentV1`. Компонент предназначен для содержимого, которое приходит из
+worker, backend или persisted state и должно содержать типографику, ссылки,
+таблицы, код, формулы, изображения, файлы и типизированные действия.
+
+`SRichDocument` renders a serializable document described by the closed
+`SRichDocumentV1` contract. It is intended for content received from a worker,
+backend, or persisted state that needs typography, links, tables, code, math,
+images, files, and typed actions.
+
+Markdown и HTML strings относятся к контракту `SDocBlock`. `SRichDocument` не
+принимает raw HTML, VNodes, callbacks, component names или trust flags.
+
+Markdown and HTML strings belong to the `SDocBlock` contract. `SRichDocument`
+does not accept raw HTML, VNodes, callbacks, component names, or trust flags.
+
+## Импорты / Imports
+
+```ts
+import SRichDocument from '@pgcorp/ui-kit/shared/data-display/SRichDocument.vue'
+import {
+  SRichDocumentContractError,
+  validateRichDocument,
+  validateRichDocumentResources,
+  type SRichDocumentActionIntent,
+  type SRichDocumentResource,
+  type SRichDocumentResourceActivate,
+  type SRichDocumentV1,
+} from '@pgcorp/ui-kit/shared/data-display/richDocument'
+```
+
+## Граница данных / Data boundary
+
+Внешний JSON проверяется в месте получения. Валидатор возвращает новый
+типизированный результат только после проверки версии, структуры, полей,
+лимитов, идентификаторов, ссылок на resources и URL policy. Renderer повторяет
+валидацию перед созданием DOM; это защищает прямое использование компонента, но
+не заменяет проверку на application boundary.
+
+Validate external JSON at the receiving boundary. The validator returns a
+typed result only after checking the version, structure, fields, limits, IDs,
+resource references, and URL policy. The renderer validates again before
+creating DOM; this protects direct component use but does not replace validation
+at the application boundary.
+
+```ts
+const document = validateRichDocument(workerMessage.document)
+const resources = validateRichDocumentResources(apiResponse.resources)
+```
+
+`SRichDocumentContractError` содержит стабильный `code`, точный `path` и
+диагностическое сообщение. Не исправляйте payload downstream и не отбрасывайте
+неизвестные nodes: ошибка означает несовместимый или опасный вход.
+
+`SRichDocumentContractError` exposes a stable `code`, an exact `path`, and a
+diagnostic message. Do not repair the payload downstream or drop unknown nodes:
+the error represents incompatible or unsafe input.
+
+```ts
+try {
+  const document = validateRichDocument(payload)
+  useDocument(document)
+} catch (error) {
+  if (error instanceof SRichDocumentContractError) {
+    reportContractFailure(error.code, error.path)
+  }
+  throw error
+}
+```
+
+Links принимают относительные application paths и `http:`, `https:`, `mailto:`,
+`tel:`. Resource records принимают относительные paths, `http:`, `https:` и
+`blob:`. Скриптовые, data, scheme-relative и неизвестные protocols отклоняются.
+Resources передаются отдельными consumer-owned records и связываются с AST по
+stable ID; UI-kit не читает filesystem и не выполняет URL самостоятельно.
+
+Links accept relative application paths plus `http:`, `https:`, `mailto:`, and
+`tel:`. Resource records accept relative paths, `http:`, `https:`, and `blob:`.
+Script, data, scheme-relative, and unknown protocols are rejected. Resources
+are supplied as separate consumer-owned records and joined to the AST by stable
+ID; the UI kit does not read the filesystem or activate URLs itself.
+
+## Модель документа / Document model
+
+`SRichDocumentV1` содержит `version: 1`, стабильный `id` и readonly `nodes`.
+Закрытая модель поддерживает:
+
+`SRichDocumentV1` contains `version: 1`, a stable `id`, and readonly `nodes`.
+The closed model supports:
+
+- paragraph, heading, strong, emphasis, inline code и links с optional
+  `current`-состоянием;
+- ordered/unordered lists, quote и divider;
+- code blocks с optional language, line numbers и label;
+- inline/block math;
+- semantic tables и callouts;
+- image/file resources по ID;
+- action groups с serializable action IDs.
+
+```ts
+const document = {
+  version: 1,
+  id: 'release-notes',
+  nodes: [
+    {
+      type: 'heading',
+      level: 1,
+      children: [{ type: 'text', value: 'Release notes' }],
+    },
+    {
+      type: 'paragraph',
+      children: [{
+        type: 'link',
+        href: '/releases/current',
+        current: true,
+        children: [{ type: 'text', value: 'Current release' }],
+      }],
+    },
+    {
+      type: 'resource',
+      resourceId: 'report',
+      label: 'Open report',
+    },
+    {
+      type: 'actionGroup',
+      label: 'Review actions',
+      actions: [{ type: 'action', id: 'approve', label: 'Approve' }],
+    },
+  ],
+} as const satisfies SRichDocumentV1
+
+const resources = [{
+  id: 'report',
+  kind: 'file',
+  url: '/reports/release.pdf',
+  label: 'Release report',
+  mediaType: 'application/pdf',
+}] as const satisfies readonly SRichDocumentResource[]
+```
+
+## Controlled intents
+
+Ссылки, resources и actions не выполняют application effects. Компонент эмитит
+`link-activate`, `resource-activate` и `action` с `documentId`, точным node
+`path` и целевым ID/URL. Consumer проверяет разрешения, выполняет навигацию,
+скачивание или доменное действие.
+
+Links, resources, and actions never execute application effects. The component
+emits `link-activate`, `resource-activate`, and `action` with the `documentId`,
+exact node `path`, and target ID or URL. The consumer authorizes and performs
+navigation, download, or domain actions.
+
+`current: true` у link-node передаёт каноническому `SLink` состояние текущего
+назначения и публикует `aria-current="page"`. Поле описывает состояние
+навигации, но не запускает переход и не меняет typed intent.
+
+`current: true` on a link node delegates the current-destination state to the
+canonical `SLink` and publishes `aria-current="page"`. The field describes
+navigation state without triggering navigation or changing the typed intent.
+
+```vue
+<SRichDocument
+  :document="document"
+  :resources="resources"
+  accessible-label="Release notes"
+  @link-activate="openLink"
+  @resource-activate="openResource"
+  @action="runDocumentAction"
+/>
+```
+
+`accessible-label` обязателен и задаёт имя root article. Consumer-owned
+`data-*` разрешены как test/tour hooks; private classes и `data-s-*` не являются
+selector API.
+
+`accessible-label` is required and names the root article. Consumer-owned
+`data-*` are supported as test and tour hooks; private classes and `data-s-*`
+are not selector APIs.
+
+## Code, math, SSR и производительность
+
+Подсветка кода и KaTeX загружаются отдельными lazy chunks. Code block использует
+read-only token presentation, а не CodeMirror editor runtime. KaTeX работает с
+`trust: false` и создаёт HTML+MathML внутри leaf renderer. Невалидная формула
+показывает локализованную диагностируемую ошибку и не превращается в trusted
+markup.
+
+Syntax highlighting and KaTeX load as separate lazy chunks. Code blocks use a
+read-only token presentation rather than the CodeMirror editor runtime. KaTeX
+runs with `trust: false` and produces HTML+MathML inside a leaf renderer. An
+invalid formula produces a localized, diagnosable error and never becomes
+trusted markup.
+
+SSR выводит стабильный безопасный fallback для code/math. Client runtime после
+mount заменяет его подсвеченным кодом и формулой. Package не использует CDN и
+не выполняет document parser в main-thread component.
+
+SSR renders stable safe fallbacks for code and math. After mount, the client
+runtime replaces them with highlighted code and rendered math. The package uses
+no CDN and runs no document parser inside the main-thread component.
+
+## Версионирование / Versioning
+
+`version` является частью persisted/transport contract. Не добавляйте
+неизвестные поля и не подменяйте версию. Новая несовместимая схема получает
+новую public version и явную migration policy; silent compatibility branches
+не используются.
+
+`version` is part of the persisted and transport contract. Do not add unknown
+fields or rewrite the version. A new incompatible schema receives a new public
+version and an explicit migration policy; silent compatibility branches are not
+used.

package/docs/scroll-viewport.md

@@ -0,0 +1,167 @@
+# Область прокрутки / Scroll viewport
+
+## Назначение / Purpose
+
+`SScrollViewport` является semantic owner прокручиваемой области. Компонент
+задаёт доступное имя, разрешённые оси, размер, focus/keyboard contract,
+overscroll policy и сериализуемое состояние границ. Consumer передаёт контент,
+но не создаёт собственный `overflow: auto` container для этого паттерна.
+
+`SScrollViewport` is the semantic owner of a scrollable region. It defines the
+accessible name, enabled axes, size, focus and keyboard contract, overscroll
+policy, and serializable boundary state. Consumers supply content instead of
+creating an application-owned `overflow: auto` container for this pattern.
+
+## Импорты / Imports
+
+```ts
+import SScrollViewport from '@pgcorp/ui-kit/shared/data-display/SScrollViewport.vue'
+import type {
+  SScrollViewportApi,
+  SScrollViewportState,
+} from '@pgcorp/ui-kit/shared/data-display/scrollViewport'
+```
+
+## Props
+
+| Prop | Contract |
+| --- | --- |
+| `accessibleLabel` | Обязательное непустое имя `region`. / Required non-empty name of the `region`. |
+| `axis` | `'x' \| 'y' \| 'both'`; default `y`. Запрещённая ось не прокручивается и недоступна API. / A disabled axis neither scrolls nor accepts API commands. |
+| `blockSize` | `'sm' \| 'md' \| 'lg' \| 'fill'`; semantic token, raw CSS length запрещён. / Semantic token; raw CSS lengths are rejected. |
+| `focusable` | Включает root tab stop и `focus()`; default `true`. / Enables the root tab stop and `focus()`; defaults to `true`. |
+| `keyboardNavigation` | Управление корнем с клавиатуры; требует `focusable=true`. / Root keyboard control; requires `focusable=true`. |
+| `overscrollBehavior` | `'auto' \| 'contain' \| 'none'`; default `contain`. |
+
+Consumer-owned `data-*` разрешены на root region для tour/test hooks. Internal
+classes и `data-s-*` не являются selector API.
+
+Consumer-owned `data-*` are supported on the root region for tour and test
+hooks. Internal classes and `data-s-*` are not selector APIs.
+
+## Состояние / State
+
+`scroll-state` эмитится после mount, прокрутки, resize viewport/content и
+изменения presentation props. Payload и вложенные записи immutable и
+serializable:
+
+`scroll-state` is emitted after mount, scrolling, viewport/content resize, and
+presentation prop changes. The payload and nested records are immutable and
+serializable:
+
+```ts
+interface SScrollViewportState {
+  readonly physical: {
+    readonly x: number
+    readonly y: number
+    readonly maxX: number
+    readonly maxY: number
+  }
+  readonly semantic: {
+    readonly inline: number
+    readonly block: number
+    readonly maxInline: number
+    readonly maxBlock: number
+  }
+  readonly atInlineStart: boolean
+  readonly atInlineEnd: boolean
+  readonly atBlockStart: boolean
+  readonly atBlockEnd: boolean
+}
+```
+
+`physical.x` измеряется от физического левого края и нормализован между
+browser RTL scroll models; `physical.y` — от верхнего края. Semantic offsets
+учитывают `direction` и `writing-mode`. Boundary flags используют semantic
+inline/block directions.
+
+`physical.x` is measured from the physical left edge and normalized across
+browser RTL scroll models; `physical.y` is measured from the top edge. Semantic
+offsets follow `direction` and `writing-mode`. Boundary flags use semantic
+inline and block directions.
+
+## Exposed API
+
+Component ref реализует только `SScrollViewportApi`; DOM owner не экспортируется:
+
+The component ref implements `SScrollViewportApi` only; its DOM owner is not
+exposed:
+
+```ts
+interface SScrollViewportApi {
+  focus(): void
+  scrollToBoundary(axis: 'x' | 'y', boundary: 'start' | 'end'): void
+  reveal(options: { x?: number; y?: number; behavior?: 'auto' | 'smooth' }): void
+}
+```
+
+`scrollToBoundary` и `reveal` проверяют разрешённые оси. Координаты `reveal`
+задаются в physical left/top model и ограничиваются фактическим scroll range.
+Вызов до mount, обращение к запрещённой оси и пустой reveal payload завершаются
+явной диагностической ошибкой.
+
+`scrollToBoundary` and `reveal` validate the enabled axes. `reveal` coordinates
+use the physical left/top model and are clamped to the actual scroll range.
+Calls before mount, commands for a disabled axis, and an empty reveal payload
+fail with explicit diagnostics.
+
+## Клавиатура и вложенные controls / Keyboard and nested controls
+
+При фокусе на root доступны:
+
+When the root owns focus:
+
+- `ArrowLeft`/`ArrowRight` — горизонтальная ось;
+- `ArrowUp`/`ArrowDown` — вертикальная ось;
+- `PageUp`/`PageDown` — вертикальная страница, либо горизонтальная при `axis="x"`;
+- `Home`/`End` — начало/конец всех разрешённых осей.
+
+Сочетания с `Alt`, `Control`, `Meta` или `Shift` компонент не перехватывает.
+Обработчик действует только когда event target совпадает с root region.
+Вложенные UI-kit inputs, editors, terminals и другие controls сохраняют свои
+клавиши, selection и native copy. Перевод фокуса на вложенный control может
+штатно прокрутить его в видимую область браузером.
+
+Combinations with `Alt`, `Control`, `Meta`, or `Shift` are not intercepted. The
+handler runs only when the event target is the root region. Nested UI-kit
+inputs, editors, terminals, and other controls retain their keys, selection,
+and native copy. Moving focus to a nested control may let the browser scroll it
+into view.
+
+## Lifecycle
+
+Один `ResizeObserver` отслеживает root viewport и content owner. Passive scroll
+listener и observer освобождаются при unmount; callback после teardown не
+публикует state. Компонент не создаёт global listener и не использует polling.
+
+One `ResizeObserver` tracks the root viewport and content owner. The passive
+scroll listener and observer are released on unmount, and callbacks after
+teardown publish no state. The component creates no global listener and uses no
+polling.
+
+## Пример / Example
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import SInputText from '@pgcorp/ui-kit/shared/controls/SInputText.vue'
+import SScrollViewport from '@pgcorp/ui-kit/shared/data-display/SScrollViewport.vue'
+import type { SScrollViewportState } from '@pgcorp/ui-kit/shared/data-display/scrollViewport'
+
+const query = ref('')
+const position = ref<SScrollViewportState | null>(null)
+</script>
+
+<template>
+  <SScrollViewport
+    accessible-label="Результаты поиска"
+    axis="both"
+    block-size="lg"
+    @scroll-state="position = $event"
+  >
+    <SInputText v-model="query" label="Поиск" />
+    <ResultsMatrix :query="query" />
+  </SScrollViewport>
+</template>
+```
+