@pgcorp/ui-kit 0.1.0

package/src/internal/codeEditorContract.ts

@@ -0,0 +1,110 @@
+import {
+  validateBoolean,
+  validateBoundedInteger,
+  validateExactString,
+  validateNonEmptyString,
+} from './runtimeContract'
+
+export const CODE_EDITOR_VIEWPORTS = ['content', 'compact', 'standard', 'expanded', 'fill'] as const
+export const CODE_EDITOR_VARIANTS = ['code', 'sql'] as const
+export const CODE_EDITOR_KEY_BEHAVIORS = ['indent', 'focus-next'] as const
+export const CODE_EDITOR_CURSOR_ACTIVITY_MODES = ['editable', 'always'] as const
+
+/**
+ * Язык задаётся явно либо определяется только из обязательного пути файла.
+ * Language is either explicit or detected exclusively from a required file path.
+ */
+export type CodeEditorLanguageContract =
+  | { mode: 'explicit'; id: string; filePath?: never }
+  | { mode: 'detect'; filePath: string; id?: never }
+
+/** Явные CodeMirror-возможности без вывода опций из presentation. / Explicit CodeMirror capabilities; no option is inferred from presentation. */
+export interface CodeEditorCapabilitiesContract {
+  lineNumbers: boolean
+  indentation: {
+    tabSize: number
+    keyBehavior: typeof CODE_EDITOR_KEY_BEHAVIORS[number]
+  }
+  keyInterceptor?: (event: KeyboardEvent) => boolean
+  cursorActivity: typeof CODE_EDITOR_CURSOR_ACTIVITY_MODES[number]
+}
+
+function isCodeEditorKeyInterceptor(value: unknown): value is (event: KeyboardEvent) => boolean {
+  return typeof value === 'function'
+}
+
+function assertPlainExactRecord(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+  allowed: readonly string[],
+): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype) {
+    throw new TypeError(`${owner}: ${coordinate} должен быть plain object. / ${owner}: ${coordinate} must be a plain object.`)
+  }
+  const record = value as Record<string, unknown>
+  const unexpected = Object.keys(record).filter((key) => !allowed.includes(key))
+  if (unexpected.length > 0) {
+    throw new TypeError(`${owner}.${coordinate}: неизвестные поля ${unexpected.map((key) => JSON.stringify(key)).join(', ')}. / ${owner}.${coordinate}: unknown fields ${unexpected.map((key) => JSON.stringify(key)).join(', ')}.`)
+  }
+  return record
+}
+
+export function validateCodeEditorLanguage(
+  owner: string,
+  value: unknown,
+): CodeEditorLanguageContract {
+  const record = assertPlainExactRecord(owner, 'language', value, ['mode', 'id', 'filePath'])
+  const mode = validateExactString(owner, 'language.mode', record.mode, ['explicit', 'detect'] as const)
+  const allowedFields = mode === 'explicit' ? ['mode', 'id'] : ['mode', 'filePath']
+  const unexpected = Object.keys(record).filter((key) => !allowedFields.includes(key))
+  if (unexpected.length > 0) {
+    throw new TypeError(
+      `${owner}.language: неизвестные поля ${unexpected.map((key) => JSON.stringify(key)).join(', ')}. `
+      + `/ ${owner}.language: unknown fields ${unexpected.map((key) => JSON.stringify(key)).join(', ')}.`,
+    )
+  }
+  if (mode === 'explicit') {
+    return { mode, id: validateNonEmptyString(owner, 'language.id', record.id) }
+  }
+  return { mode, filePath: validateNonEmptyString(owner, 'language.filePath', record.filePath) }
+}
+
+export function validateCodeEditorCapabilities(
+  owner: string,
+  value: unknown,
+): CodeEditorCapabilitiesContract {
+  const record = assertPlainExactRecord(
+    owner,
+    'capabilities',
+    value,
+    ['lineNumbers', 'indentation', 'keyInterceptor', 'cursorActivity'],
+  )
+  const indentation = assertPlainExactRecord(
+    owner,
+    'capabilities.indentation',
+    record.indentation,
+    ['tabSize', 'keyBehavior'],
+  )
+  const keyInterceptor = record.keyInterceptor
+  if (keyInterceptor !== undefined && !isCodeEditorKeyInterceptor(keyInterceptor)) {
+    throw new TypeError(`${owner}: capabilities.keyInterceptor должен быть функцией. / ${owner}: capabilities.keyInterceptor must be a function.`)
+  }
+  return {
+    lineNumbers: validateBoolean(owner, 'capabilities.lineNumbers', record.lineNumbers),
+    indentation: {
+      tabSize: validateBoundedInteger(owner, 'capabilities.indentation.tabSize', indentation.tabSize, { minimum: 1, maximum: 16 }),
+      keyBehavior: validateExactString(owner, 'capabilities.indentation.keyBehavior', indentation.keyBehavior, CODE_EDITOR_KEY_BEHAVIORS),
+    },
+    ...(keyInterceptor === undefined ? {} : { keyInterceptor }),
+    cursorActivity: validateExactString(owner, 'capabilities.cursorActivity', record.cursorActivity, CODE_EDITOR_CURSOR_ACTIVITY_MODES),
+  }
+}
+
+export function validateCodeEditorViewport(owner: string, value: unknown): typeof CODE_EDITOR_VIEWPORTS[number] {
+  return validateExactString(owner, 'viewport', value, CODE_EDITOR_VIEWPORTS)
+}
+
+export function validateCodeEditorVariant(owner: string, value: unknown): typeof CODE_EDITOR_VARIANTS[number] {
+  return validateExactString(owner, 'variant', value, CODE_EDITOR_VARIANTS)
+}

package/src/internal/codeEditorExtensions.ts

@@ -0,0 +1,27 @@
+import type { ComputedRef, InjectionKey } from 'vue'
+import { inject, provide } from 'vue'
+import type { Extension } from '@codemirror/state'
+
+export type TrustedCodeEditorExtensionOwner = 'SSqlEditor'
+
+interface TrustedCodeEditorExtensionChannel {
+  owner: TrustedCodeEditorExtensionOwner
+  extensions: ComputedRef<readonly Extension[]>
+}
+
+const TRUSTED_CODE_EDITOR_EXTENSION_KEY: InjectionKey<TrustedCodeEditorExtensionChannel> = Symbol(
+  'sputnig-ui-kit-trusted-code-editor-extensions',
+)
+
+/** Internal-only CodeMirror extension channel for audited UI-kit adapters. */
+export function provideTrustedCodeEditorExtensions(
+  owner: TrustedCodeEditorExtensionOwner,
+  extensions: ComputedRef<readonly Extension[]>,
+): void {
+  provide(TRUSTED_CODE_EDITOR_EXTENSION_KEY, { owner, extensions })
+}
+
+/** Consumes extensions supplied by the nearest audited UI-kit adapter. */
+export function useTrustedCodeEditorExtensions(): TrustedCodeEditorExtensionChannel | null {
+  return inject(TRUSTED_CODE_EDITOR_EXTENSION_KEY, null)
+}

package/src/internal/feedbackPresentation.ts

@@ -0,0 +1,136 @@
+import type { Component } from 'vue'
+
+import { AlertTriangle, CheckCircle2, Info, LoaderCircle, XCircle } from '../components/icons/sputnigUiIcons'
+
+export type FeedbackTone = 'neutral' | 'info' | 'success' | 'warn' | 'danger'
+export type FeedbackSeverity = Exclude<FeedbackTone, 'neutral'>
+export type FeedbackLiveMode = 'off' | 'polite' | 'assertive' | 'auto'
+export type AsyncFeedbackStatus = 'loading' | 'empty' | 'error'
+export type FeedbackIndicatorState = FeedbackTone | 'progress'
+
+export interface FeedbackPresentation {
+  icon: Component
+  iconName: 'info' | 'check-circle' | 'alert-triangle' | 'x-circle'
+  fallbackTitle: string
+}
+
+export interface FeedbackLiveAttributes {
+  role?: 'status' | 'alert'
+  ariaLive?: 'polite' | 'assertive'
+  ariaAtomic?: 'true'
+}
+
+export interface AsyncFeedbackPresentation {
+  readonly tone: FeedbackTone
+  readonly icon: Component | null
+  readonly iconName: FeedbackPresentation['iconName'] | 'loader-circle' | null
+  readonly fallbackMessage: string
+  readonly busy: boolean
+  readonly live: Readonly<FeedbackLiveAttributes>
+}
+
+export interface FeedbackIndicatorPresentation {
+  readonly tone: FeedbackTone
+  readonly icon: Component
+  readonly iconName: FeedbackPresentation['iconName'] | 'loader-circle'
+  readonly fallbackTitle: string
+  readonly motion: 'static' | 'spin'
+}
+
+const presentations: Readonly<Record<FeedbackTone, Readonly<FeedbackPresentation>>> = {
+  neutral: { icon: Info, iconName: 'info', fallbackTitle: 'Статус' },
+  info: { icon: Info, iconName: 'info', fallbackTitle: 'Информация' },
+  success: { icon: CheckCircle2, iconName: 'check-circle', fallbackTitle: 'Успех' },
+  warn: { icon: AlertTriangle, iconName: 'alert-triangle', fallbackTitle: 'Предупреждение' },
+  danger: { icon: XCircle, iconName: 'x-circle', fallbackTitle: 'Ошибка' },
+}
+
+/**
+ * Возвращает единую icon/title-презентацию для feedback tone.
+ * Returns the canonical icon/title presentation for a feedback tone.
+ */
+export function resolveFeedbackPresentation(tone: FeedbackTone): Readonly<FeedbackPresentation> {
+  return presentations[tone]
+}
+
+/**
+ * Возвращает единственный icon/tone/motion contract для status indicator.
+ * Returns the canonical icon/tone/motion contract for a status indicator.
+ */
+export function resolveFeedbackIndicator(
+  state: FeedbackIndicatorState,
+): Readonly<FeedbackIndicatorPresentation> {
+  if (state === 'progress') {
+    return {
+      tone: 'info',
+      icon: LoaderCircle,
+      iconName: 'loader-circle',
+      fallbackTitle: 'Выполняется',
+      motion: 'spin',
+    }
+  }
+  const presentation = resolveFeedbackPresentation(state)
+  return {
+    tone: state,
+    icon: presentation.icon,
+    iconName: presentation.iconName,
+    fallbackTitle: presentation.fallbackTitle,
+    motion: 'static',
+  }
+}
+
+/**
+ * Выражает live-region contract без привязки к визуальному компоненту.
+ * Resolves live-region semantics independently from a visual component.
+ */
+export function resolveFeedbackLive(
+  tone: FeedbackTone,
+  mode: FeedbackLiveMode,
+): Readonly<FeedbackLiveAttributes> {
+  if (mode === 'off') return {}
+  const politeness = mode === 'auto' ? (tone === 'danger' ? 'assertive' : 'polite') : mode
+  return {
+    role: politeness === 'assertive' ? 'alert' : 'status',
+    ariaLive: politeness,
+    ariaAtomic: 'true',
+  }
+}
+
+/**
+ * Возвращает единый визуальный и live-region contract для async surface state.
+ * Returns the canonical visual and live-region contract for an async surface state.
+ */
+export function resolveAsyncFeedbackPresentation(
+  status: AsyncFeedbackStatus,
+): Readonly<AsyncFeedbackPresentation> {
+  if (status === 'loading') {
+    const progress = resolveFeedbackIndicator('progress')
+    return {
+      tone: progress.tone,
+      icon: progress.icon,
+      iconName: progress.iconName,
+      fallbackMessage: 'Загрузка…',
+      busy: true,
+      live: resolveFeedbackLive(progress.tone, 'auto'),
+    }
+  }
+  if (status === 'empty') {
+    return {
+      tone: 'neutral',
+      icon: null,
+      iconName: null,
+      fallbackMessage: 'Нет данных для отображения.',
+      busy: false,
+      live: resolveFeedbackLive('neutral', 'auto'),
+    }
+  }
+  const error = resolveFeedbackIndicator('danger')
+  return {
+    tone: 'danger',
+    icon: error.icon,
+    iconName: error.iconName,
+    fallbackMessage: error.fallbackTitle,
+    busy: false,
+    live: resolveFeedbackLive('danger', 'auto'),
+  }
+}

package/src/internal/fieldSurface.ts

@@ -0,0 +1,59 @@
+import { validateBoolean, validateExactString, validateNonEmptyString } from './runtimeContract'
+
+const FIELD_SURFACE_KINDS = [
+  'text-input',
+  'textarea',
+  'inline-token-editor',
+  'combobox-trigger',
+] as const
+const FIELD_SURFACE_APPEARANCES = ['field', 'ghost', 'embedded'] as const
+
+/** Canonical owners sharing one field-surface visual contract. / Канонические владельцы общего визуального контракта field surface. */
+export type FieldSurfaceKind = typeof FIELD_SURFACE_KINDS[number]
+/** Canonical participation mode in the shared field surface. / Режим участия в общей field surface. */
+export type FieldSurfaceAppearance = typeof FIELD_SURFACE_APPEARANCES[number]
+
+export interface FieldSurfaceContract {
+  kind: FieldSurfaceKind
+  appearance: FieldSurfaceAppearance
+  invalid: boolean
+  disabled: boolean
+  readonly: boolean
+}
+
+export interface FieldSurfaceBindings {
+  'data-s-field-surface': FieldSurfaceKind
+  'data-s-field-appearance': FieldSurfaceAppearance
+  'data-s-field-invalid'?: 'true'
+  'data-s-field-disabled'?: 'true'
+  'data-s-field-readonly'?: 'true'
+}
+
+/**
+ * Создаёт exact DOM bindings единого field-surface foundation без truthy coercion.
+ * Creates exact DOM bindings for the shared field-surface foundation without truthy coercion.
+ */
+export function resolveFieldSurfaceBindings(
+  owner: string,
+  contract: FieldSurfaceContract,
+): FieldSurfaceBindings {
+  validateNonEmptyString('fieldSurface', 'owner', owner)
+  const kind = validateExactString(owner, 'field surface kind', contract.kind, FIELD_SURFACE_KINDS)
+  const appearance = validateExactString(
+    owner,
+    'field surface appearance',
+    contract.appearance,
+    FIELD_SURFACE_APPEARANCES,
+  )
+  const invalid = validateBoolean(owner, 'field surface invalid', contract.invalid)
+  const disabled = validateBoolean(owner, 'field surface disabled', contract.disabled)
+  const readonly = validateBoolean(owner, 'field surface readonly', contract.readonly)
+
+  return {
+    'data-s-field-surface': kind,
+    'data-s-field-appearance': appearance,
+    ...(invalid ? { 'data-s-field-invalid': 'true' as const } : {}),
+    ...(disabled ? { 'data-s-field-disabled': 'true' as const } : {}),
+    ...(readonly ? { 'data-s-field-readonly': 'true' as const } : {}),
+  }
+}

package/src/internal/focusNavigation.ts

@@ -0,0 +1,69 @@
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'textarea:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  '[contenteditable="true"]',
+  '[tabindex]:not([tabindex="-1"])',
+].join(', ')
+
+const isSemanticallyVisible = (element: HTMLElement): boolean => {
+  if (element.hidden || element.closest('[inert]') || element.closest('[aria-hidden="true"]')) return false
+  const style = window.getComputedStyle(element)
+  return style.display !== 'none' && style.visibility !== 'hidden'
+}
+
+/** Проверяет programmatic/browser focus owner без layout-эвристик. / Checks a programmatic/browser focus owner without layout heuristics. */
+export const isFocusableElement = (element: HTMLElement): boolean => (
+  element.matches(FOCUSABLE_SELECTOR) && isSemanticallyVisible(element)
+)
+
+/**
+ * Поднимает произвольный event target до ближайшего canonical focus owner внутри optional boundary.
+ * Lifts an arbitrary event target to the nearest canonical focus owner inside an optional boundary.
+ */
+export const findFocusableOwner = (
+  target: EventTarget | null,
+  boundary?: ParentNode | null,
+): HTMLElement | null => {
+  const targetElement = target instanceof Element
+    ? target
+    : target instanceof Node
+      ? target.parentElement
+      : null
+  const owner = targetElement?.closest<HTMLElement>(FOCUSABLE_SELECTOR) ?? null
+  if (!owner || !isFocusableElement(owner)) return null
+  if (boundary instanceof Node && !boundary.contains(owner)) return null
+  return owner
+}
+
+export const getFocusableElements = (
+  root: ParentNode,
+  options: { requireLayout?: boolean } = {},
+): HTMLElement[] => [...root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)].filter((element) => {
+  if (!isFocusableElement(element)) return false
+  if (!options.requireLayout) return true
+  return element.offsetParent !== null || element.getClientRects().length > 0
+})
+
+export const findRelativeTabTarget = (
+  reference: HTMLElement,
+  scope: ParentNode,
+  excludedRoot: HTMLElement | null,
+  reverse: boolean,
+): HTMLElement | null => {
+  const candidates = getFocusableElements(scope).filter((element) => !excludedRoot?.contains(element))
+  if (candidates.length === 0) return null
+  const exactIndex = candidates.indexOf(reference)
+  if (exactIndex >= 0) {
+    const offset = reverse ? -1 : 1
+    return candidates[(exactIndex + offset + candidates.length) % candidates.length] ?? null
+  }
+
+  const ordered = reverse ? [...candidates].reverse() : candidates
+  const relation = reverse ? Node.DOCUMENT_POSITION_PRECEDING : Node.DOCUMENT_POSITION_FOLLOWING
+  return ordered.find((candidate) => Boolean(reference.compareDocumentPosition(candidate) & relation))
+    ?? ordered[0]
+    ?? null
+}

package/src/internal/inlineTokenEditorContract.ts

@@ -0,0 +1,136 @@
+import { validateBoundedInteger, validateNonEmptyString } from './runtimeContract'
+
+export type InlineTokenEditorSegmentContract =
+  | { readonly kind: 'text'; readonly text: string }
+  | {
+    readonly kind: 'token'
+    readonly occurrenceId: string
+    readonly id: string
+    readonly label: string
+    readonly title?: string
+  }
+
+function assertPlainRecord(owner: string, value: unknown): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype) {
+    throw new TypeError(`${owner}: значение должно быть plain object. / ${owner}: value must be a plain object.`)
+  }
+  return value as Record<string, unknown>
+}
+
+function assertExactKeys(owner: string, record: Record<string, unknown>, allowed: readonly string[]): void {
+  const unexpected = Object.keys(record).filter((key) => !allowed.includes(key))
+  if (unexpected.length > 0) {
+    throw new TypeError(`${owner}: неизвестные поля ${unexpected.map((key) => JSON.stringify(key)).join(', ')}. / ${owner}: unknown fields ${unexpected.map((key) => JSON.stringify(key)).join(', ')}.`)
+  }
+}
+
+/** Собирает plain-text mirror без нормализации сегментов. / Builds the plain-text mirror without normalizing segments. */
+export function inlineTokenSegmentsToText(segments: readonly InlineTokenEditorSegmentContract[]): string {
+  return segments.map((segment) => segment.kind === 'text' ? segment.text : segment.label).join('')
+}
+
+/** Проверяет canonical external segment source и его exact model mirror. / Validates the canonical external segment source and its exact model mirror. */
+export function parseInlineTokenEditorSource(
+  modelValue: unknown,
+  segments: unknown,
+): readonly InlineTokenEditorSegmentContract[] {
+  if (typeof modelValue !== 'string') {
+    throw new TypeError('SInlineTokenEditor: modelValue должен быть строкой. / SInlineTokenEditor: modelValue must be a string.')
+  }
+  if (!Array.isArray(segments)) {
+    throw new TypeError('SInlineTokenEditor: segments должен быть массивом. / SInlineTokenEditor: segments must be an array.')
+  }
+
+  const parsed: InlineTokenEditorSegmentContract[] = []
+  const tokenOccurrences = new Map<string, number>()
+  for (let index = 0; index < segments.length; index += 1) {
+    if (!Object.hasOwn(segments, index)) {
+      throw new TypeError(`SInlineTokenEditor: segments[${index}] отсутствует в sparse array. / SInlineTokenEditor: segments[${index}] is missing from a sparse array.`)
+    }
+    const record = assertPlainRecord(`SInlineTokenEditor.segments[${index}]`, segments[index])
+    if (record.kind === 'text') {
+      assertExactKeys(`SInlineTokenEditor.segments[${index}]`, record, ['kind', 'text'])
+      if (typeof record.text !== 'string' || record.text.length === 0) {
+        throw new TypeError(`SInlineTokenEditor: segments[${index}].text должен быть непустой строкой. / SInlineTokenEditor: segments[${index}].text must be a non-empty string.`)
+      }
+      const text = record.text
+      if (parsed.at(-1)?.kind === 'text') {
+        throw new TypeError(`SInlineTokenEditor: segments[${index}] является смежным text segment; объедините его в источнике. / SInlineTokenEditor: segments[${index}] is an adjacent text segment; merge it at the source.`)
+      }
+      parsed.push({ kind: 'text', text })
+      continue
+    }
+    if (record.kind !== 'token') {
+      throw new TypeError(`SInlineTokenEditor: segments[${index}].kind должен быть "text" или "token". / SInlineTokenEditor: segments[${index}].kind must be "text" or "token".`)
+    }
+    assertExactKeys(`SInlineTokenEditor.segments[${index}]`, record, ['kind', 'occurrenceId', 'id', 'label', 'title'])
+    const occurrenceId = validateNonEmptyString(
+      'SInlineTokenEditor', `segments[${index}].occurrenceId`, record.occurrenceId,
+    )
+    const firstOccurrenceIndex = tokenOccurrences.get(occurrenceId)
+    if (firstOccurrenceIndex !== undefined) {
+      throw new TypeError(`SInlineTokenEditor: segments[${index}].occurrenceId дублирует ${JSON.stringify(occurrenceId)} из segments[${firstOccurrenceIndex}].occurrenceId. / SInlineTokenEditor: segments[${index}].occurrenceId duplicates ${JSON.stringify(occurrenceId)} from segments[${firstOccurrenceIndex}].occurrenceId.`)
+    }
+    tokenOccurrences.set(occurrenceId, index)
+    const title = record.title === undefined
+      ? undefined
+      : validateNonEmptyString('SInlineTokenEditor', `segments[${index}].title`, record.title)
+    parsed.push({
+      kind: 'token',
+      occurrenceId,
+      id: validateNonEmptyString('SInlineTokenEditor', `segments[${index}].id`, record.id),
+      label: validateNonEmptyString('SInlineTokenEditor', `segments[${index}].label`, record.label),
+      ...(title === undefined ? {} : { title }),
+    })
+  }
+
+  const mirror = inlineTokenSegmentsToText(parsed)
+  if (modelValue !== mirror) {
+    throw new TypeError(`SInlineTokenEditor: modelValue не совпадает с text mirror segments; ожидалось ${JSON.stringify(mirror)}, получено ${JSON.stringify(modelValue)}. / SInlineTokenEditor: modelValue does not match the segments text mirror; expected ${JSON.stringify(mirror)}, received ${JSON.stringify(modelValue)}.`)
+  }
+  return parsed
+}
+
+/** Проверяет cursor offset относительно exact logical text. / Validates a cursor offset against exact logical text. */
+export function validateInlineTokenCursorOffset(value: unknown, textLength: number, coordinate: string): number {
+  return validateBoundedInteger('SInlineTokenEditor', coordinate, value, { minimum: 0, maximum: textLength })
+}
+
+/** Запрещает cursor внутри atomic token label; разрешены только его границы. / Rejects cursor positions inside an atomic token label; only its boundaries are addressable. */
+export function validateInlineTokenCursorBoundary(
+  segments: readonly InlineTokenEditorSegmentContract[],
+  value: unknown,
+  coordinate: string,
+): number {
+  const offset = validateInlineTokenCursorOffset(value, inlineTokenSegmentsToText(segments).length, coordinate)
+  let segmentStart = 0
+  for (const segment of segments) {
+    const segmentEnd = segmentStart + (segment.kind === 'text' ? segment.text.length : segment.label.length)
+    if (segment.kind === 'token' && offset > segmentStart && offset < segmentEnd) {
+      throw new RangeError(`SInlineTokenEditor: ${coordinate}=${offset} попадает внутрь atomic token occurrence ${JSON.stringify(segment.occurrenceId)}; допустимы ${segmentStart} или ${segmentEnd}. / SInlineTokenEditor: ${coordinate}=${offset} falls inside atomic token occurrence ${JSON.stringify(segment.occurrenceId)}; use ${segmentStart} or ${segmentEnd}.`)
+    }
+    segmentStart = segmentEnd
+  }
+  return offset
+}
+
+/** Создаёт canonical internally-generated sequence; external invalid input сюда не попадает. / Creates a canonical internally-generated sequence; external invalid input never enters this path. */
+export function composeInlineTokenSegments(
+  segments: readonly InlineTokenEditorSegmentContract[],
+): InlineTokenEditorSegmentContract[] {
+  const result: InlineTokenEditorSegmentContract[] = []
+  for (const segment of segments) {
+    if (segment.kind === 'text') {
+      if (segment.text.length === 0) continue
+      const previous = result.at(-1)
+      if (previous?.kind === 'text') {
+        result[result.length - 1] = { kind: 'text', text: previous.text + segment.text }
+      } else {
+        result.push({ kind: 'text', text: segment.text })
+      }
+    } else {
+      result.push({ ...segment })
+    }
+  }
+  return [...parseInlineTokenEditorSource(inlineTokenSegmentsToText(result), result)]
+}

package/src/internal/interactiveElement.ts

@@ -0,0 +1,33 @@
+/**
+ * Типизированная element/focus-поверхность UI-kit leaf для составных владельцев.
+ * Typed element/focus surface exposed by a UI-kit leaf to composite owners.
+ */
+export interface ElementApi<TElement extends HTMLElement = HTMLElement> {
+  getElement: () => TElement
+}
+
+export interface InteractiveElementApi<TElement extends HTMLElement = HTMLElement> extends ElementApi<TElement> {
+  focus: (options?: FocusOptions) => void
+}
+
+export type ElementRefTarget = Element | ElementApi | ComponentPublicInstance | null
+export type InteractiveElementRefTarget = Element | InteractiveElementApi | ComponentPublicInstance | null
+
+/** Разрешает callback-ref только через native HTMLElement или публичный leaf API. / Resolves a callback ref only through a native HTMLElement or a public leaf API. */
+export function resolveInteractiveElement(
+  owner: string,
+  target: ElementRefTarget,
+): HTMLElement | null {
+  if (target === null) return null
+  if (target instanceof HTMLElement) return target
+  const getElement = Reflect.get(target, 'getElement')
+  if (typeof getElement !== 'function') {
+    throw new TypeError(`${owner}: ref must resolve to an HTMLElement or ElementApi`)
+  }
+  const element: unknown = Reflect.apply(getElement, target, [])
+  if (!(element instanceof HTMLElement)) {
+    throw new TypeError(`${owner}: ElementApi.getElement() must return an HTMLElement`)
+  }
+  return element
+}
+import type { ComponentPublicInstance } from 'vue'