@pgcorp/ui-kit 0.9.0 → 0.10.0

package/src/components/shared/controls/_internal/SInlineTokenSurface.vue

@@ -10,6 +10,7 @@ import {
 } from 'vue'
 
 import { X } from '../../../icons/sputnigUiIcons'
+import { useUiKitLocale } from '../../../../composables/useUiKitLocale'
 import type { FieldSurfaceBindings } from '../../../../internal/fieldSurface'
 import type { InlineTokenEditorSegmentContract } from '../../../../internal/inlineTokenEditorContract'
 import type { OwnedAttributeBindings } from '../../../../internal/ownedAttrs'
@@ -121,6 +122,7 @@ export default defineComponent({
     ),
   },
   setup(props, { emit }) {
+    const { t } = useUiKitLocale()
     useInteractiveLeafRegistration({
       owner: 'SInlineTokenEditor',
       active: () => !props.disabled,
@@ -143,7 +145,7 @@ export default defineComponent({
       const bindings: InlineTokenActionButtonBindings = action === 'open'
         ? {
             label: segment.label,
-            'aria-label': segment.title ? `Открыть ${segment.title}` : `Открыть ${segment.label}`,
+            'aria-label': t('forms.openToken', { label: segment.title ?? segment.label }),
             ...(segment.title === undefined ? {} : { title: segment.title }),
             size: 'xs',
             width: 'fit',
@@ -155,7 +157,7 @@ export default defineComponent({
           }
         : {
             leadingIcon: X,
-            'aria-label': `Убрать ${segment.label}`,
+            'aria-label': t('forms.removeToken', { label: segment.label }),
             size: 'xs',
             appearance: 'ghost',
             shape: 'circle',

package/src/components/shared/data-display/SChart.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { computed, onBeforeUnmount, onMounted, ref, shallowRef, watchEffect } from 'vue'
+import { useUiKitLocale } from '../../../composables/useUiKitLocale'
 import { useOwnedAttrs } from '../../../internal/ownedAttrs'
 import { resolveChartModel } from '../../../internal/chartGeometry'
 import type { ChartDimensions } from '../../../internal/chartGeometry'
@@ -76,9 +77,10 @@ const props = withDefaults(defineProps<Props>(), {
   centerLabel: undefined,
   centerValue: undefined,
   dataTablePresentation: 'assistive',
-  emptyLabel: 'Нет данных для графика',
+  emptyLabel: undefined,
   valueFormatter: undefined,
 })
+const { t } = useUiKitLocale()
 
 const ownedAttrs = useOwnedAttrs({ component: 'SChart', owner: 'chart root' })
 const viewportElement = ref<HTMLElement | null>(null)
@@ -147,7 +149,7 @@ const resolvedValueFormatter = computed(() => {
   return props.valueFormatter
 })
 const validatedEmptyLabel = computed(() => validateNonEmptyString(
-  'SChart', 'emptyLabel', props.emptyLabel,
+  'SChart', 'emptyLabel', props.emptyLabel ?? t('chart.empty'),
 ))
 const validatedXAxisLabel = computed(() => props.xAxisLabel === undefined
   ? undefined
@@ -223,7 +225,7 @@ const showVerticalGrid = computed(() => validatedGrid.value === 'vertical' || va
 const showTable = computed(() => validatedTablePresentation.value !== 'none' && !model.value.empty)
 const tableClass = computed(() => validatedTablePresentation.value === 'assistive' ? 's-chart__data-table--assistive' : undefined)
 const emptyTitle = computed(() => model.value.emptyReason === 'zero-total'
-  ? 'Нет ненулевых значений для графика'
+  ? t('chart.noNonZeroValues')
   : validatedEmptyLabel.value)
 const accessibleLabel = computed(() => accessibility.value.mode === 'label' ? accessibility.value.label : undefined)
 const accessibleDescription = computed(() => accessibility.value.mode === 'label' ? accessibility.value.description : undefined)
@@ -471,12 +473,12 @@ watchEffect(() => {
       v-if="showTable"
       class="s-chart__data-table"
       :class="tableClass"
-      :aria-label="accessibility.mode === 'label' ? `${accessibility.label}: данные` : undefined"
+      :aria-label="accessibility.mode === 'label' ? t('chart.dataFor', { chart: accessibility.label }) : undefined"
       :aria-labelledby="accessibility.mode === 'labelledby' ? accessibility.id : undefined"
     >
       <thead>
         <tr>
-          <th scope="col">Категория</th>
+          <th scope="col">{{ t('chart.category') }}</th>
           <th v-for="item in series" :key="item.key" scope="col">{{ item.label }}</th>
         </tr>
       </thead>

package/src/components/shared/data-display/SChip.vue

@@ -41,6 +41,7 @@
 <script setup lang="ts">
 import { computed, type Component } from 'vue'
 import { X } from '../../icons/sputnigUiIcons'
+import { useUiKitLocale } from '../../../composables/useUiKitLocale'
 import { useOwnedAttrs } from '../../../internal/ownedAttrs'
 import {
   PILL_ICON_CLASS,
@@ -89,6 +90,7 @@ const emit = defineEmits<{
   activate: [event: MouseEvent]
 }>()
 const ownedAttrs = useOwnedAttrs({ component: 'SChip', owner: 'chip root' })
+const { t } = useUiKitLocale()
 
 const validatedLabel = computed(() => validateNonEmptyString('SChip', 'label', props.label))
 const validatedSeverity = computed(() => validateExactString(
@@ -120,7 +122,7 @@ const resolvedCloseLabel = computed(() => {
   validateBoolean('SChip', 'closable', props.closable)
   validateBoolean('SChip', 'disabled', props.disabled)
   return props.closeLabel === undefined
-    ? `Удалить «${validatedLabel.value}»`
+    ? t('actions.removeChip', { label: validatedLabel.value })
     : validateNonEmptyString('SChip', 'closeLabel', props.closeLabel)
 })
 </script>

package/src/components/shared/data-display/SCodeBlock.css

@@ -111,6 +111,10 @@
   grid-template-columns: max-content minmax(0, 1fr);
 }
 
+.s-code-block-plain__line[data-line-numbers='hidden'] {
+  display: block;
+}
+
 .s-code-block-plain__line-number {
   min-width: 2.5rem;
   padding-inline-end: 0.75rem;

package/src/components/shared/data-display/SCodeBlock.vue

@@ -22,8 +22,8 @@
           size="xs"
           :leading-icon="Copy"
           icon-only
-          title="Копировать код"
-          aria-label="Копировать код"
+          :title="t('clipboard.copyCode')"
+          :aria-label="t('clipboard.copyCode')"
           label=""
           @click="copyCode"
         />
@@ -47,7 +47,7 @@
         @ready="onReady"
       />
       <pre
-        v-else
+        v-else-if="validatedPresentation === 'plain'"
         :ref="setPlainSurface"
         class="s-code-block-plain"
         :data-viewport="validatedViewport"
@@ -61,11 +61,30 @@
           :key="index"
           class="s-code-block-plain__line"
         ><span class="s-code-block-plain__line-number" aria-hidden="true">{{ index + 1 }}</span><span class="s-code-block-plain__line-content">{{ line || '\u200b' }}</span></span></code></pre>
+      <pre
+        v-else
+        :ref="setPlainSurface"
+        class="s-code-block-plain"
+        :data-viewport="validatedViewport"
+        :aria-label="props.ariaLabel"
+        :aria-labelledby="props.ariaLabelledby"
+        :style="{ tabSize: validatedTabSize }"
+        tabindex="0"
+      ><span class="s-code-block-plain__lines"><span
+          v-for="(line, index) in plainLines"
+          :key="index"
+          class="s-code-block-plain__line"
+          :data-line-numbers="validatedShowLineNumbers ? 'visible' : 'hidden'"
+        ><span v-if="validatedShowLineNumbers" class="s-code-block-plain__line-number" aria-hidden="true">{{ index + 1 }}</span><span class="s-code-block-plain__line-content"><SCodeTokenLine
+            :text="line || '\u200b'"
+            :language="validatedLanguage"
+            variant="code-block"
+          /></span></span></span></pre>
     </div>
     <SAsyncState
       v-if="validatedErrorMessage !== undefined || (validatedPresentation === 'editor' && !isReady)"
       :state="validatedErrorMessage === undefined
-        ? { status: 'loading', message: 'Загрузка кода...' }
+        ? { status: 'loading', message: t('editor.loading') }
         : { status: 'error', message: validatedErrorMessage }"
       presentation="overlay"
     />
@@ -80,6 +99,7 @@ import { validateCodeEditorLanguage, validateCodeEditorViewport } from '../../..
 import { resolveCodeLanguageKey } from '../../../internal/codeLanguageIdentity';
 import { useNotifier } from '../../../composables/useNotifier';
 import { useClipboard } from '../../../composables/useClipboard';
+import { useUiKitLocale } from '../../../composables/useUiKitLocale';
 import SButton from '../controls/SButton.vue';
 import type {
   SCodeEditorCapabilities,
@@ -91,6 +111,7 @@ import type {
 } from './SCodeEditor.vue';
 import { Copy } from '../../icons/sputnigUiIcons';
 import SAsyncState from '../feedback/SAsyncState.vue';
+import SCodeTokenLine from './_internal/SCodeTokenLine.vue';
 
 defineOptions({ inheritAttrs: false });
 
@@ -102,7 +123,7 @@ type AccessibleName =
 export type Props = AccessibleName & {
   code: string;
   language: SCodeEditorLanguage;
-  presentation?: 'editor' | 'plain';
+  presentation?: 'editor' | 'plain' | 'highlighted';
   showHeader?: boolean;
   showLineNumbers?: boolean;
   readOnly?: boolean;
@@ -150,7 +171,7 @@ const validatedShowHeader = computed(() => validateBoolean('SCodeBlock', 'showHe
 const validatedShowLineNumbers = computed(() => validateBoolean('SCodeBlock', 'showLineNumbers', props.showLineNumbers));
 const validatedReadOnly = computed(() => validateBoolean('SCodeBlock', 'readOnly', props.readOnly));
 const validatedPresentation = computed(() => validateExactString(
-  'SCodeBlock', 'presentation', props.presentation, ['editor', 'plain'] as const,
+  'SCodeBlock', 'presentation', props.presentation, ['editor', 'plain', 'highlighted'] as const,
 ));
 const validatedSurfaceRadius = computed(() => validateExactString(
   'SCodeBlock', 'surfaceRadius', props.surfaceRadius, ['default', 'none', 'xl'] as const,
@@ -200,7 +221,7 @@ const emitPlainReady = (): void => {
 
 const syncPresentation = (): void => {
   if (!mounted) return;
-  if (validatedPresentation.value === 'plain') emitPlainReady();
+  if (validatedPresentation.value !== 'editor') emitPlainReady();
   else isReady.value = false;
 };
 
@@ -213,14 +234,14 @@ watch(validatedPresentation, syncPresentation);
 watch(
   [validatedPresentation, validatedReadOnly],
   ([presentation, readOnly]) => {
-    if (presentation === 'plain' && !readOnly) {
-      throw new TypeError('SCodeBlock: presentation="plain" поддерживает только readOnly=true. / SCodeBlock: presentation="plain" supports readOnly=true only.');
+    if (presentation !== 'editor' && !readOnly) {
+      throw new TypeError(`SCodeBlock: presentation=${JSON.stringify(presentation)} поддерживает только readOnly=true. / SCodeBlock: presentation=${JSON.stringify(presentation)} supports readOnly=true only.`);
     }
-    if (presentation === 'plain' && props.interceptKeys !== undefined) {
-      throw new TypeError('SCodeBlock: presentation="plain" не принимает interceptKeys. / SCodeBlock: presentation="plain" does not accept interceptKeys.');
+    if (presentation !== 'editor' && props.interceptKeys !== undefined) {
+      throw new TypeError(`SCodeBlock: presentation=${JSON.stringify(presentation)} не принимает interceptKeys. / SCodeBlock: presentation=${JSON.stringify(presentation)} does not accept interceptKeys.`);
     }
-    if (presentation === 'plain' && props.nextSelectionPos !== null) {
-      throw new TypeError('SCodeBlock: presentation="plain" не принимает nextSelectionPos. / SCodeBlock: presentation="plain" does not accept nextSelectionPos.');
+    if (presentation !== 'editor' && props.nextSelectionPos !== null) {
+      throw new TypeError(`SCodeBlock: presentation=${JSON.stringify(presentation)} не принимает nextSelectionPos. / SCodeBlock: presentation=${JSON.stringify(presentation)} does not accept nextSelectionPos.`);
     }
   },
   { immediate: true },
@@ -234,8 +255,8 @@ const setPlainSurface = (element: Element | ComponentPublicInstance | null): voi
 };
 
 const applySelection = (position: number): void => {
-  if (validatedPresentation.value === 'plain') {
-    throw new Error('SCodeBlock: applySelection недоступен в presentation="plain". / SCodeBlock: applySelection is unavailable in presentation="plain".');
+  if (validatedPresentation.value !== 'editor') {
+    throw new Error(`SCodeBlock: applySelection недоступен в presentation=${JSON.stringify(validatedPresentation.value)}. / SCodeBlock: applySelection is unavailable in presentation=${JSON.stringify(validatedPresentation.value)}.`);
   }
   const editor = codeEditor.value;
   if (!editor) throw new Error('SCodeBlock: editor не готов; дождитесь ready. / SCodeBlock: editor is not ready; wait for ready.');
@@ -243,7 +264,7 @@ const applySelection = (position: number): void => {
 };
 
 const focus = (): void => {
-  if (validatedPresentation.value === 'plain') {
+  if (validatedPresentation.value !== 'editor') {
     const surface = plainSurface.value;
     if (!surface) throw new Error('SCodeBlock: plain surface не готов; дождитесь ready. / SCodeBlock: plain surface is not ready; wait for ready.');
     surface.focus();
@@ -256,19 +277,20 @@ const focus = (): void => {
 
 defineExpose({ applySelection, focus });
 const notifier = useNotifier();
+const { t } = useUiKitLocale();
 const { copyText } = useClipboard();
 const copyCode = async () => {
   const result = await copyText(props.code);
   if (result.status === 'copied') {
-    notifier.success({ message: 'Код скопирован' });
+    notifier.success({ message: t('clipboard.codeCopied') });
     return;
   }
   notifier.danger({
     message: result.status === 'unavailable'
-      ? 'Копирование недоступно в этом браузере'
+      ? t('clipboard.codeCopyUnavailable')
       : result.status === 'empty'
-        ? 'Нет кода для копирования'
-        : `Ошибка копирования. ${result.error.message}`,
+        ? t('clipboard.emptyCode')
+        : `${t('clipboard.codeCopyFailed')} ${result.error.message}`,
   });
 };
 </script>

package/src/components/shared/data-display/SCodeEditor.css

@@ -87,6 +87,23 @@
   @apply text-surface-400 dark:text-surface-500;
 }
 
+.s-code-editor :deep(.cm-lintRange-error) {
+  text-decoration-color: var(--s-code-editor-diagnostic-error);
+}
+
+.s-code-editor :deep(.cm-lintRange-warning) {
+  text-decoration-color: var(--s-code-editor-diagnostic-warning);
+}
+
+.s-code-editor :deep(.cm-lintRange-info),
+.s-code-editor :deep(.cm-lintRange-hint) {
+  text-decoration-color: var(--s-code-editor-diagnostic-info);
+}
+
+.s-code-editor__diagnostics {
+  @apply sr-only;
+}
+
 .s-code-editor :deep(.cm-tooltip) {
   @apply rounded-md border border-surface-200 bg-surface-0 text-surface-900 shadow-lg;
   @apply dark:border-surface-700 dark:bg-surface-800 dark:text-surface-100;

package/src/components/shared/data-display/SCodeEditor.vue

@@ -13,13 +13,28 @@
     @ready="onReady"
     @update:model-value="onUpdate"
   />
+  <div
+    v-if="validatedDiagnostics.length > 0"
+    :id="diagnosticsOwnerId"
+    class="s-code-editor__diagnostics"
+    role="status"
+    aria-live="polite"
+    aria-atomic="true"
+  >
+    <ul>
+      <li v-for="diagnostic in validatedDiagnostics" :key="diagnostic.id">
+        {{ diagnostic.message }}
+      </li>
+    </ul>
+  </div>
 </template>
 
 <script setup lang="ts">
-import { computed, ref, watch } from 'vue'
+import { computed, onBeforeUnmount, ref, shallowRef, useId, watch } from 'vue'
 import { Codemirror } from 'vue-codemirror'
 import { oneDark } from '@codemirror/theme-one-dark'
 import { EditorSelection, EditorState, type Extension } from '@codemirror/state'
+import { lintGutter, setDiagnostics, type Diagnostic as CodeMirrorDiagnostic } from '@codemirror/lint'
 import { EditorView, lineNumbers, placeholder as codeMirrorPlaceholder } from '@codemirror/view'
 import { useOwnedAttrs } from '../../../internal/ownedAttrs'
 import { useInteractiveLeafRegistration } from '../../../internal/passiveContentContract'
@@ -42,6 +57,18 @@ import {
   validateCodeEditorViewport,
 } from '../../../internal/codeEditorContract'
 import { getCodeMirrorLanguageExtension, resolveCodeLanguageKey } from '../codeLanguages'
+import {
+  type SCodeEditorDiagnostic,
+  type SCodeEditorDiagnosticId,
+  type SCodeEditorApi,
+  type SCodeEditorRange,
+  type SCodeEditorSelectionRange,
+  type SCodeEditorSelectionSnapshot,
+  type SCodeEditorViewState,
+  validateCodeEditorDiagnostics,
+  validateCodeEditorRange,
+  validateCodeEditorViewState,
+} from './codeEditor'
 
 defineOptions({ inheritAttrs: false })
 
@@ -92,6 +119,8 @@ export type Props = AccessibleName & {
   viewport?: SCodeEditorViewport
   variant?: SCodeEditorVariant
   nextSelectionPos?: number | null
+  /** Controlled diagnostics expressed only through serializable UI-kit ranges. */
+  diagnostics?: readonly SCodeEditorDiagnostic<SCodeEditorDiagnosticId>[]
   /** DOM id supplemental status/diagnostic owner. / DOM id of a supplemental status/diagnostic owner. */
   ariaDescribedby?: string
   /** Помечает editor content невалидным без владения presentation диагностики. / Marks the editor content as invalid without owning diagnostic presentation. */
@@ -106,6 +135,7 @@ const props = withDefaults(defineProps<Props>(), {
   viewport: 'content',
   variant: 'code',
   nextSelectionPos: null,
+  diagnostics: () => [],
   ariaDescribedby: undefined,
   invalid: false,
 })
@@ -113,6 +143,8 @@ const props = withDefaults(defineProps<Props>(), {
 const emit = defineEmits<{
   'update:modelValue': [value: string]
   'cursor-activity': [payload: SCodeEditorCursorActivity]
+  'selection-change': [payload: SCodeEditorSelectionRange]
+  'view-state-change': [payload: SCodeEditorViewState]
   'selection-applied': [payload: SCodeEditorSelectionAppliedPayload]
   ready: [payload: SCodeEditorReadyPayload]
 }>()
@@ -122,8 +154,12 @@ useInteractiveLeafRegistration({ owner: 'SCodeEditor' })
 
 const runtimeTheme = useRuntimeTheme()
 const trustedChannel = useTrustedCodeEditorExtensions()
-const editorView = ref<EditorView | null>(null)
+const editorView = shallowRef<EditorView | null>(null)
 const pendingControlledSelection = ref<number | null>(null)
+const diagnosticsOwnerId = `s-code-editor-diagnostics-${useId()}`
+let scrollOwner: HTMLElement | null = null
+let lastSelection: SCodeEditorSelectionRange | null = null
+let lastViewState: SCodeEditorViewState | null = null
 
 const validatedModelValue = computed(() => {
   if (typeof props.modelValue === 'string') return props.modelValue
@@ -137,6 +173,11 @@ const validatedReadOnly = computed(() => validateBoolean('SCodeEditor', 'readOnl
 const validatedDisabled = computed(() => validateBoolean('SCodeEditor', 'disabled', props.disabled))
 const validatedInvalid = computed(() => validateBoolean('SCodeEditor', 'invalid', props.invalid))
 const isLocked = computed(() => validatedReadOnly.value || validatedDisabled.value)
+const validatedDiagnostics = computed(() => validateCodeEditorDiagnostics(
+  'SCodeEditor',
+  props.diagnostics,
+  validatedModelValue.value.length,
+))
 
 const resolvedLanguage = computed((): SCodeEditorLanguage => {
   const language = validateCodeEditorLanguage('SCodeEditor', props.language)
@@ -166,9 +207,12 @@ const contentAttributes = computed((): Record<string, string> => {
   } else {
     throw new TypeError('SCodeEditor: требуется ariaLabel или ariaLabelledby. / SCodeEditor: ariaLabel or ariaLabelledby is required.')
   }
-  if (props.ariaDescribedby !== undefined) {
-    attributes['aria-describedby'] = validateDomId('SCodeEditor', 'ariaDescribedby', props.ariaDescribedby)
-  }
+  attributes.tabindex = validatedDisabled.value ? '-1' : '0'
+  const describedBy = props.ariaDescribedby === undefined
+    ? []
+    : [validateDomId('SCodeEditor', 'ariaDescribedby', props.ariaDescribedby)]
+  if (validatedDiagnostics.value.length > 0) describedBy.push(diagnosticsOwnerId)
+  if (describedBy.length > 0) attributes['aria-describedby'] = describedBy.join(' ')
   if (validatedInvalid.value) attributes['aria-invalid'] = 'true'
   if (validatedReadOnly.value) attributes['aria-readonly'] = 'true'
   if (validatedDisabled.value) attributes['aria-disabled'] = 'true'
@@ -197,6 +241,7 @@ const resolvedExtensions = computed<Extension[]>(() => {
   if (languageExtension) result.push(languageExtension)
   if (runtimeTheme.value.mode === 'dark') result.push(oneDark)
   if (capabilities.lineNumbers) result.push(lineNumbers())
+  if (validatedDiagnostics.value.length > 0) result.push(lintGutter())
   if (props.placeholder !== undefined) result.push(codeMirrorPlaceholder(validateNonEmptyString('SCodeEditor', 'placeholder', props.placeholder)))
   result.push(EditorState.readOnly.of(isLocked.value))
   result.push(EditorView.editable.of(!isLocked.value))
@@ -211,6 +256,7 @@ const resolvedExtensions = computed<Extension[]>(() => {
   }
   result.push(EditorView.updateListener.of((update) => {
     editorView.value = update.view
+    if (update.selectionSet || update.docChanged) emitSelectionAndViewState(update.view)
     if ((isLocked.value && capabilities.cursorActivity !== 'always') || (!update.selectionSet && !update.docChanged)) return
     const pos = update.state.selection.main.head
     const line = update.state.doc.lineAt(pos)
@@ -238,6 +284,93 @@ const dispatchSelection = (position: number, source: SCodeEditorSelectionApplied
   emit('selection-applied', { position: validated, source })
 }
 
+const requireEditorView = (): EditorView => {
+  const view = editorView.value
+  if (!view) throw new Error('SCodeEditor: editor не готов; дождитесь ready. / SCodeEditor: editor is not ready; wait for ready.')
+  return view
+}
+
+const freezeSelection = (view: EditorView): SCodeEditorSelectionRange => {
+  const range = view.state.selection.main
+  return Object.freeze({
+    anchor: range.anchor,
+    head: range.head,
+    from: range.from,
+    to: range.to,
+    empty: range.empty,
+  })
+}
+
+const captureViewStateFrom = (view: EditorView): SCodeEditorViewState => Object.freeze({
+  selection: freezeSelection(view),
+  scrollTop: view.scrollDOM.scrollTop,
+  scrollLeft: view.scrollDOM.scrollLeft,
+})
+
+const selectionsEqual = (
+  left: SCodeEditorSelectionRange | null,
+  right: SCodeEditorSelectionRange,
+): boolean => left !== null
+  && left.anchor === right.anchor
+  && left.head === right.head
+  && left.from === right.from
+  && left.to === right.to
+  && left.empty === right.empty
+
+const viewStatesEqual = (left: SCodeEditorViewState | null, right: SCodeEditorViewState): boolean =>
+  left !== null
+  && selectionsEqual(left.selection, right.selection)
+  && left.scrollTop === right.scrollTop
+  && left.scrollLeft === right.scrollLeft
+
+const emitSelectionAndViewState = (view: EditorView): void => {
+  const selection = freezeSelection(view)
+  if (!selectionsEqual(lastSelection, selection)) {
+    lastSelection = selection
+    emit('selection-change', selection)
+  }
+  const viewState = captureViewStateFrom(view)
+  if (!viewStatesEqual(lastViewState, viewState)) {
+    lastViewState = viewState
+    emit('view-state-change', viewState)
+  }
+}
+
+const emitScrollViewState = (): void => {
+  const view = editorView.value
+  if (!view) return
+  const viewState = captureViewStateFrom(view)
+  if (viewStatesEqual(lastViewState, viewState)) return
+  lastViewState = viewState
+  emit('view-state-change', viewState)
+}
+
+const detachScrollOwner = (): void => {
+  scrollOwner?.removeEventListener('scroll', emitScrollViewState)
+  scrollOwner = null
+}
+
+const attachScrollOwner = (view: EditorView): void => {
+  detachScrollOwner()
+  scrollOwner = view.scrollDOM
+  scrollOwner.addEventListener('scroll', emitScrollViewState, { passive: true })
+}
+
+const toCodeMirrorDiagnostics = (
+  diagnostics: readonly SCodeEditorDiagnostic<SCodeEditorDiagnosticId>[],
+): readonly CodeMirrorDiagnostic[] => diagnostics.map((diagnostic) => ({
+  from: diagnostic.from,
+  to: diagnostic.to,
+  severity: diagnostic.severity,
+  message: diagnostic.message,
+  ...(diagnostic.source === undefined ? {} : { source: diagnostic.source }),
+}))
+
+const syncDiagnostics = (view: EditorView): void => {
+  const diagnostics = validateCodeEditorDiagnostics('SCodeEditor', props.diagnostics, view.state.doc.length)
+  view.dispatch(setDiagnostics(view.state, toCodeMirrorDiagnostics(diagnostics)))
+}
+
 const onUpdate = (value: string): void => {
   if (typeof value !== 'string') {
     throw new TypeError('SCodeEditor: CodeMirror update payload должен быть строкой. / SCodeEditor: CodeMirror update payload must be a string.')
@@ -250,6 +383,8 @@ const onReady = (payload: unknown): void => {
     throw new TypeError('SCodeEditor: CodeMirror ready payload должен содержать EditorView. / SCodeEditor: CodeMirror ready payload must contain EditorView.')
   }
   editorView.value = (payload as { view: EditorView }).view
+  attachScrollOwner(editorView.value)
+  syncDiagnostics(editorView.value)
   const readyPayload: SCodeEditorReadyPayload = {
     documentLength: editorView.value.state.doc.length,
     viewport: validatedViewport.value,
@@ -276,11 +411,41 @@ watch(() => props.nextSelectionPos, (position) => {
   dispatchSelection(position, 'controlled')
 }, { immediate: true })
 
-defineExpose({
+watch(validatedDiagnostics, () => {
+  if (editorView.value) syncDiagnostics(editorView.value)
+})
+
+onBeforeUnmount(() => {
+  detachScrollOwner()
+  editorView.value = null
+  lastSelection = null
+  lastViewState = null
+})
+
+defineExpose<SCodeEditorApi>({
   applySelection: (position: number) => dispatchSelection(position, 'imperative'),
+  revealRange: (range: SCodeEditorRange) => {
+    const view = requireEditorView()
+    const validated = validateCodeEditorRange('SCodeEditor', 'revealRange', range, view.state.doc.length)
+    const effect = EditorView.scrollIntoView(EditorSelection.range(validated.from, validated.to), { y: 'nearest' })
+    view.dispatch({ effects: effect })
+  },
+  getSelection: (): SCodeEditorSelectionSnapshot => {
+    const view = requireEditorView()
+    const selection = freezeSelection(view)
+    return Object.freeze({ ...selection, text: view.state.doc.sliceString(selection.from, selection.to) })
+  },
+  captureViewState: (): SCodeEditorViewState => captureViewStateFrom(requireEditorView()),
+  applyViewState: (viewState: SCodeEditorViewState) => {
+    const view = requireEditorView()
+    const validated = validateCodeEditorViewState('SCodeEditor', viewState, view.state.doc.length)
+    view.dispatch({ selection: EditorSelection.range(validated.selection.anchor, validated.selection.head) })
+    view.scrollDOM.scrollTop = validated.scrollTop
+    view.scrollDOM.scrollLeft = validated.scrollLeft
+    emitSelectionAndViewState(view)
+  },
   focus: () => {
-    if (!editorView.value) throw new Error('SCodeEditor: editor не готов; дождитесь ready. / SCodeEditor: editor is not ready; wait for ready.')
-    editorView.value.focus()
+    requireEditorView().focus()
   },
 })
 </script>