@pgcorp/ui-kit 0.1.0

package/src/components/shared/controls/SInlineTokenEditor.vue

@@ -0,0 +1,1081 @@
+<template>
+  <SField
+    :control-id="editorId"
+    :label="label"
+    :required="validatedRequired"
+    :help-text="helpText"
+    :error-message="errorMessage"
+    :invalid="validatedInvalid"
+    :disabled="validatedDisabled"
+    :readonly="validatedReadonly"
+    :fill="validatedAppearance === 'ghost' ? 'container' : 'content'"
+  >
+    <template #default="field">
+      <SInlineTokenSurface
+        :id="editorId"
+        :element-ref="bindInlineEditorElement"
+        :owned-attributes="ownedAttrs.bindings()"
+        :field-bindings="resolveFieldBindings(field)"
+        :segments="inlineSegments"
+        :trailing-caret-helper="hasTrailingInlineCaretHelper"
+        :open-disabled="validatedDisabled"
+        :remove-disabled="validatedDisabled || validatedReadonly"
+        :appearance="validatedAppearance"
+        :invalid="field.invalid"
+        :disabled="field.disabled"
+        :readonly="field.readonly"
+        :required="field.required"
+        :rows="rows"
+        :max-rows="maxRows"
+        :placeholder="placeholder"
+        :placeholder-visible="isInlinePlaceholderVisible"
+        :labelled-by="mergeIdReferences(ownedAttrs.string('aria-labelledby'), field.labelledBy)"
+        :described-by="mergeIdReferences(ownedAttrs.string('aria-describedby'), field.describedBy)"
+        @beforeinput="handleInlineBeforeInput"
+        @input="handleInlineInput"
+        @keydown="handleInlineKeydown"
+        @keyup="handleInlineKeyup"
+        @click="handleInlineClick"
+        @paste="handleInlinePaste"
+        @token-action="handleInlineTokenAction"
+      />
+    </template>
+  </SField>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, useId, watch } from 'vue'
+import { mergeIdReferences, useOwnedAttrs } from '../../../internal/ownedAttrs'
+import { resolveFieldSurfaceBindings, type FieldSurfaceBindings } from '../../../internal/fieldSurface'
+import {
+  composeInlineTokenSegments,
+  type InlineTokenEditorSegmentContract,
+  inlineTokenSegmentsToText,
+  parseInlineTokenEditorSource,
+  validateInlineTokenCursorBoundary,
+} from '../../../internal/inlineTokenEditorContract'
+import {
+  validateBoolean,
+  validateBoundedInteger,
+  validateDomId,
+  validateExactString,
+  validateNonEmptyString,
+} from '../../../internal/runtimeContract'
+import SInlineTokenSurface, {
+  INLINE_TOKEN_EDITOR_VISUAL_CARET_TEXT,
+  type InlineTokenActionEvent,
+  type InlineTokenElementRef,
+} from './_internal/SInlineTokenSurface.vue'
+import SField from './SField.vue'
+
+defineOptions({
+  inheritAttrs: false,
+})
+
+/** Canonical text/token segment без nullable/fallback states. / Canonical text/token segment without nullable or fallback states. */
+export type SInlineTokenEditorSegment = InlineTokenEditorSegmentContract
+
+/** Public editor contract с exact model mirror и semantic row sizing. / Public editor contract with an exact model mirror and semantic row sizing. */
+export interface Props {
+  modelValue: string
+  segments: readonly SInlineTokenEditorSegment[]
+  label?: string
+  placeholder?: string
+  disabled?: boolean
+  readonly?: boolean
+  required?: boolean
+  invalid?: boolean
+  errorMessage?: string
+  helpText?: string
+  id?: string
+  rows?: number
+  maxRows?: number
+  appearance?: 'default' | 'ghost'
+}
+
+/** Exact text/cursor state after a user or imperative edit. / Exact text/cursor state после user или imperative edit. */
+export interface SInlineTokenEditorState {
+  text: string
+  cursor: number
+}
+
+/** Exact identity of one token occurrence and its domain entity. / Точная identity одного вхождения токена и его доменной сущности. */
+export interface SInlineTokenEditorTokenReference {
+  occurrenceId: string
+  id: string
+}
+
+/** Atomic controlled replacement request with one cursor commit. / Атомарный запрос controlled-замены с единым commit курсора. */
+export interface SInlineTokenEditorReplacement {
+  start: number
+  end: number
+  segments: readonly SInlineTokenEditorSegment[]
+  cursor: number
+}
+
+/** Public imperative surface for focus, selection, and atomic domain insertions. / Публичная imperative-поверхность focus, selection и атомарных доменных вставок. */
+export interface SInlineTokenEditorApi {
+  focus: () => void
+  insertSoftLineBreak: () => void
+  getSelectionOffset: () => number
+  queueSelectionOffset: (offset: number) => void
+  setSelectionOffset: (offset: number) => void
+  replaceRange: (replacement: SInlineTokenEditorReplacement) => void
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  label: undefined,
+  placeholder: undefined,
+  disabled: false,
+  readonly: false,
+  required: false,
+  invalid: false,
+  errorMessage: undefined,
+  helpText: undefined,
+  id: undefined,
+  rows: 3,
+  maxRows: 0,
+  appearance: 'default',
+})
+
+const emit = defineEmits<{
+  (e: 'update:modelValue', value: string): void
+  (e: 'update:segments', value: SInlineTokenEditorSegment[]): void
+  (e: 'keydown', event: KeyboardEvent): void
+  (e: 'keyup', event: KeyboardEvent): void
+  (e: 'click', event: MouseEvent): void
+  (e: 'open-token', token: SInlineTokenEditorTokenReference): void
+  (e: 'remove-token', token: SInlineTokenEditorTokenReference): void
+  (e: 'state-change', state: SInlineTokenEditorState): void
+}>()
+const ownedAttrs = useOwnedAttrs({ component: 'SInlineTokenEditor', owner: 'inline token editing surface' })
+
+const generatedEditorId = useId()
+const editorId = computed(() => props.id === undefined
+  ? `s-inline-token-editor-${generatedEditorId}`
+  : validateDomId('SInlineTokenEditor', 'id', props.id))
+
+const inlineEditorRef = ref<HTMLDivElement | null>(null)
+const bindInlineEditorElement: InlineTokenElementRef = (target) => {
+  if (target !== null && !(target instanceof HTMLDivElement)) {
+    throw new TypeError('SInlineTokenEditor: editing surface ref должен быть HTMLDivElement. / SInlineTokenEditor: editing surface ref must be an HTMLDivElement.')
+  }
+  inlineEditorRef.value = target
+}
+const lastSelectionOffset = ref(0)
+const pendingInlineSelectionOffset = ref<number | null>(null)
+const inlineSelectionOffsetToRestore = ref<number | null>(null)
+const INLINE_VISUAL_CARET_TEXT = INLINE_TOKEN_EDITOR_VISUAL_CARET_TEXT
+
+const inlineSegments = computed<readonly SInlineTokenEditorSegment[]>(() =>
+  parseInlineTokenEditorSource(props.modelValue, props.segments))
+const validatedDisabled = computed(() => validateBoolean('SInlineTokenEditor', 'disabled', props.disabled))
+const validatedReadonly = computed(() => validateBoolean('SInlineTokenEditor', 'readonly', props.readonly))
+const validatedRequired = computed(() => validateBoolean('SInlineTokenEditor', 'required', props.required))
+const validatedInvalid = computed(() => validateBoolean('SInlineTokenEditor', 'invalid', props.invalid))
+const validatedAppearance = computed(() => validateExactString(
+  'SInlineTokenEditor', 'appearance', props.appearance, ['default', 'ghost'] as const,
+))
+
+const hasSemanticInlineContent = computed(() => inlineSegments.value.length > 0)
+const isInlinePlaceholderVisible = computed(() => !hasSemanticInlineContent.value)
+const inlineTrailingCaretHelperKind = computed<'newline' | 'token' | null>(() => {
+  const inlineText = segmentsToText(inlineSegments.value)
+  if (inlineText.endsWith('\n')) {
+    return 'newline'
+  }
+
+  const lastSegment = inlineSegments.value[inlineSegments.value.length - 1]
+  if (lastSegment?.kind === 'token') {
+    return 'token'
+  }
+
+  return null
+})
+const hasTrailingInlineCaretHelper = computed(() => inlineTrailingCaretHelperKind.value !== null)
+const inlineDomSignature = computed(() => JSON.stringify({
+  segments: inlineSegments.value,
+  trailingCaretHelperKind: inlineTrailingCaretHelperKind.value,
+  tokenRemovalDisabled: validatedDisabled.value || validatedReadonly.value,
+}))
+
+
+function resolveFieldBindings(field: {
+  invalid: boolean
+  disabled: boolean
+  readonly: boolean
+}): FieldSurfaceBindings {
+  return resolveFieldSurfaceBindings('SInlineTokenEditor', {
+    kind: 'inline-token-editor',
+    appearance: validatedAppearance.value === 'default' ? 'field' : 'ghost',
+    invalid: field.invalid,
+    disabled: field.disabled,
+    readonly: field.readonly,
+  })
+}
+
+const segmentsToText = (segments: readonly SInlineTokenEditorSegment[]): string =>
+  inlineTokenSegmentsToText(segments)
+
+const isInlineVisualCaretTextNode = (node: Node): node is Text =>
+  node.nodeType === Node.TEXT_NODE && node.textContent === INLINE_VISUAL_CARET_TEXT
+
+const getInlineTokenLogicalLength = (node: HTMLElement): number =>
+  validateNonEmptyString('SInlineTokenEditor', 'DOM token label', node.dataset.segmentLabel).length
+
+const findLastInlineTextNode = (
+  nodes: Iterable<Node>,
+  predicate: (node: Node) => node is Text,
+): Text | null => {
+  const entries = Array.from(nodes)
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const candidate = entries[index]
+    if (candidate && predicate(candidate)) {
+      return candidate
+    }
+  }
+  return null
+}
+
+const findFirstEditableInlineTextNode = (node: Node | null): Text | null => {
+  if (!node) {
+    return null
+  }
+  if (node.nodeType === Node.TEXT_NODE) {
+    const textNode = node as Text
+    return isInlineVisualCaretTextNode(textNode) ? null : textNode
+  }
+
+  for (const child of Array.from(node.childNodes)) {
+    const found = findFirstEditableInlineTextNode(child)
+    if (found) {
+      return found
+    }
+  }
+
+  return null
+}
+
+const getNodeLogicalLength = (node: Node): number => {
+  if (node.nodeType === Node.TEXT_NODE) {
+    if (isInlineVisualCaretTextNode(node)) {
+      return 0
+    }
+    return (node as Text).data.length
+  }
+  if (node instanceof HTMLElement && node.dataset.segmentKind === 'token') {
+    return getInlineTokenLogicalLength(node)
+  }
+  let total = 0
+  node.childNodes.forEach((child) => {
+    total += getNodeLogicalLength(child)
+  })
+  return total
+}
+
+const validateDomBoundaryOffset = (node: Node, offset: number, coordinate: string): number => {
+  if (!Number.isInteger(offset)) {
+    throw new TypeError(`SInlineTokenEditor: ${coordinate} должен быть целым DOM offset. / SInlineTokenEditor: ${coordinate} must be an integer DOM offset.`)
+  }
+  const maximum = node.nodeType === Node.TEXT_NODE
+    ? (node as Text).data.length
+    : node.childNodes.length
+  if (offset < 0 || offset > maximum) {
+    throw new RangeError(`SInlineTokenEditor: ${coordinate}=${offset} вне DOM range [0, ${maximum}]. / SInlineTokenEditor: ${coordinate}=${offset} is outside DOM range [0, ${maximum}].`)
+  }
+  return offset
+}
+
+const calculateOffsetWithin = (root: Node, target: Node, targetOffset: number): number => {
+  if (root === target) {
+    const validatedTargetOffset = validateDomBoundaryOffset(target, targetOffset, 'selection boundary')
+    if (root.nodeType === Node.TEXT_NODE) {
+      if (isInlineVisualCaretTextNode(root)) {
+        return 0
+      }
+      return validatedTargetOffset
+    }
+    let subtotal = 0
+    const children = Array.from(root.childNodes)
+    for (let index = 0; index < validatedTargetOffset; index += 1) {
+      subtotal += getNodeLogicalLength(children[index]!)
+    }
+    return subtotal
+  }
+
+  if (root.nodeType === Node.TEXT_NODE) {
+    if (isInlineVisualCaretTextNode(root)) {
+      return 0
+    }
+    return (root as Text).data.length
+  }
+
+  if (root instanceof HTMLElement && root.dataset.segmentKind === 'token') {
+    return getInlineTokenLogicalLength(root)
+  }
+
+  let total = 0
+  for (const child of Array.from(root.childNodes)) {
+    if (child === target || child.contains(target)) {
+      total += calculateOffsetWithin(child, target, targetOffset)
+      return total
+    }
+    total += getNodeLogicalLength(child)
+  }
+  throw new RangeError('SInlineTokenEditor: selection boundary не принадлежит editing surface. / SInlineTokenEditor: selection boundary does not belong to the editing surface.')
+}
+
+const getActiveInlineSelectionOffset = (
+  source: readonly SInlineTokenEditorSegment[],
+  coordinate: string,
+): number => {
+  const editor = inlineEditorRef.value
+  if (!editor) {
+    throw new Error('SInlineTokenEditor: editing surface не готова для getSelectionOffset. / SInlineTokenEditor: editing surface is not ready for getSelectionOffset.')
+  }
+  const selection = window.getSelection()
+  if (!selection) {
+    throw new Error('SInlineTokenEditor: Selection API недоступен для getSelectionOffset. / SInlineTokenEditor: Selection API is unavailable for getSelectionOffset.')
+  }
+  if (selection.rangeCount === 0) {
+    throw new Error('SInlineTokenEditor: активная selection отсутствует для getSelectionOffset. / SInlineTokenEditor: no active selection exists for getSelectionOffset.')
+  }
+  const range = selection.getRangeAt(0)
+  if (!editor.contains(range.startContainer) && range.startContainer !== editor) {
+    throw new Error('SInlineTokenEditor: активная selection не принадлежит editing surface. / SInlineTokenEditor: the active selection does not belong to the editing surface.')
+  }
+  if (range.startContainer === editor && editor.childNodes.length === 0) {
+    validateDomBoundaryOffset(editor, range.startOffset, 'empty editor selection boundary')
+    lastSelectionOffset.value = 0
+    return 0
+  }
+  const offset = validateInlineTokenCursorBoundary(
+    source,
+    calculateOffsetWithin(editor, range.startContainer, range.startOffset),
+    coordinate,
+  )
+  lastSelectionOffset.value = offset
+  return offset
+}
+
+const getInlineSelectionOffset = (): number => getActiveInlineSelectionOffset(
+  inlineSegments.value,
+  'active selection offset',
+)
+
+const buildInlineRangeAtOffset = (editor: HTMLDivElement, offset: number): Range => {
+  const range = document.createRange()
+  const source = inlineSegments.value
+  const validatedOffset = validateInlineTokenCursorBoundary(source, offset, 'selection offset')
+  let remaining = validatedOffset
+  const inlineText = segmentsToText(source)
+  if (hasTrailingInlineCaretHelper.value && validatedOffset === inlineText.length) {
+    const visualCaretNode = findLastInlineTextNode(editor.childNodes, isInlineVisualCaretTextNode)
+    if (visualCaretNode) {
+      range.setStart(visualCaretNode, visualCaretNode.data.length)
+      range.collapse(true)
+      return range
+    }
+  }
+
+  const placeWithin = (node: Node): boolean => {
+    if (node.nodeType === Node.TEXT_NODE) {
+      if (isInlineVisualCaretTextNode(node)) {
+        range.setStart(node, (node as Text).data.length)
+        range.collapse(true)
+        return true
+      }
+      const length = (node as Text).data.length
+      if (remaining > length) {
+        throw new RangeError(`SInlineTokenEditor: selection traversal overflow ${remaining} > ${length}.`)
+      }
+      range.setStart(node, remaining)
+      range.collapse(true)
+      return true
+    }
+
+    if (node instanceof HTMLElement && node.dataset.segmentKind === 'token') {
+      const tokenLength = getInlineTokenLogicalLength(node)
+      const parent = node.parentNode
+      if (!parent) return false
+      const children = Array.from(parent.childNodes)
+      const nodeIndex = children.indexOf(node)
+      if (remaining === 0) {
+        range.setStart(parent, nodeIndex)
+        range.collapse(true)
+        return true
+      }
+      if (remaining === tokenLength) {
+        const nextTextNode = findFirstEditableInlineTextNode(children[nodeIndex + 1] ?? null)
+        if (nextTextNode) {
+          range.setStart(nextTextNode, 0)
+          range.collapse(true)
+          return true
+        }
+
+        const trailingCaretNode = findLastInlineTextNode(editor.childNodes, isInlineVisualCaretTextNode)
+        if (trailingCaretNode) {
+          range.setStart(trailingCaretNode, trailingCaretNode.data.length)
+          range.collapse(true)
+          return true
+        }
+
+        range.setStart(parent, nodeIndex + 1)
+        range.collapse(true)
+        return true
+      }
+      if (remaining < tokenLength) {
+        throw new RangeError(`SInlineTokenEditor: selection offset ${remaining} попал внутрь atomic token ${JSON.stringify(node.dataset.segmentId)}. / SInlineTokenEditor: selection offset ${remaining} fell inside atomic token ${JSON.stringify(node.dataset.segmentId)}.`)
+      }
+      remaining -= tokenLength
+      return false
+    }
+
+    const children = Array.from(node.childNodes)
+    if (!children.length) {
+      range.setStart(node, 0)
+      range.collapse(true)
+      return true
+    }
+
+    for (const child of children) {
+      const childLength = getNodeLogicalLength(child)
+      if (remaining <= childLength) {
+        return placeWithin(child)
+      }
+      remaining -= childLength
+    }
+
+    range.setStart(node, children.length)
+    range.collapse(true)
+    return true
+  }
+
+  placeWithin(editor)
+  return range
+}
+
+const placeInlineSelectionAtOffset = (offset: number): void => {
+  const editor = inlineEditorRef.value
+  if (!editor) {
+    throw new Error('SInlineTokenEditor: editing surface не готова. / SInlineTokenEditor: editing surface is not ready.')
+  }
+
+  const selection = window.getSelection()
+  if (!selection) {
+    throw new Error('SInlineTokenEditor: Selection API недоступен. / SInlineTokenEditor: Selection API is unavailable.')
+  }
+
+  const range = buildInlineRangeAtOffset(editor, offset)
+  selection.removeAllRanges()
+  selection.addRange(range)
+  lastSelectionOffset.value = validateInlineTokenCursorBoundary(inlineSegments.value, offset, 'placed selection offset')
+}
+
+const emitInlineEditorState = (textOverride?: string): void => {
+  emit('state-change', {
+    text: textOverride ?? segmentsToText(inlineSegments.value),
+    cursor: getInlineSelectionOffset(),
+  })
+}
+
+const readInlineSegmentsFromDom = (): SInlineTokenEditorSegment[] => {
+  const editor = inlineEditorRef.value
+  if (!editor) {
+    throw new Error('SInlineTokenEditor: невозможно прочитать DOM до readiness. / SInlineTokenEditor: cannot read DOM before readiness.')
+  }
+  if (
+    editor.childNodes.length === 1
+    && editor.firstChild instanceof HTMLBRElement
+  ) {
+    return []
+  }
+
+  const segments: SInlineTokenEditorSegment[] = []
+  const appendText = (text: string) => {
+    if (!text) return
+    const previous = segments[segments.length - 1]
+    if (previous?.kind === 'text') {
+      segments[segments.length - 1] = { kind: 'text', text: previous.text + text }
+    } else {
+      segments.push({ kind: 'text', text })
+    }
+  }
+
+  const visit = (node: Node): void => {
+    if (node.nodeType === Node.TEXT_NODE) {
+      if (isInlineVisualCaretTextNode(node)) {
+        return
+      }
+      appendText((node as Text).data)
+      return
+    }
+
+    if (node instanceof HTMLElement && node.dataset.segmentKind === 'token') {
+      const candidate = {
+        kind: 'token' as const,
+        occurrenceId: node.dataset.segmentOccurrenceId,
+        id: node.dataset.segmentId,
+        label: node.dataset.segmentLabel,
+        ...(node.dataset.segmentTitle === undefined ? {} : { title: node.dataset.segmentTitle }),
+      }
+      const parsed = parseInlineTokenEditorSource(candidate.label, [candidate])
+      const token = parsed[0]
+      if (!token || token.kind !== 'token') {
+        throw new TypeError('SInlineTokenEditor: token DOM parser не создал token segment. / SInlineTokenEditor: token DOM parser did not produce a token segment.')
+      }
+      segments.push(token)
+      return
+    }
+
+    if (node.nodeType === Node.COMMENT_NODE) return
+    throw new TypeError(`SInlineTokenEditor: неожиданный DOM node ${node.nodeName} вне canonical text/token grammar. / SInlineTokenEditor: unexpected DOM node ${node.nodeName} outside the canonical text/token grammar.`)
+  }
+
+  editor.childNodes.forEach((node) => visit(node))
+  return segments
+}
+
+const emitInlineSegmentsFromDom = (): void => {
+  const nextSegments = readInlineSegmentsFromDom()
+  const nextText = segmentsToText(nextSegments)
+  parseInlineTokenEditorSource(nextText, nextSegments)
+  const nextCursor = getActiveInlineSelectionOffset(nextSegments, 'input selection offset')
+  lastSelectionOffset.value = nextCursor
+  pendingInlineSelectionOffset.value = nextCursor
+  emit('update:segments', nextSegments)
+  emit('update:modelValue', nextText)
+  emit('state-change', {
+    text: nextText,
+    cursor: nextCursor,
+  })
+}
+
+const commitInlineSegmentsUpdate = (
+  segments: readonly SInlineTokenEditorSegment[],
+  cursor: number,
+): void => {
+  const nextSegments = composeInlineTokenSegments(segments)
+  const nextText = segmentsToText(nextSegments)
+  parseInlineTokenEditorSource(nextText, nextSegments)
+  const nextCursor = validateInlineTokenCursorBoundary(nextSegments, cursor, 'committed cursor offset')
+  lastSelectionOffset.value = nextCursor
+  pendingInlineSelectionOffset.value = nextCursor
+  emit('update:segments', nextSegments)
+  emit('update:modelValue', nextText)
+  emit('state-change', {
+    text: nextText,
+    cursor: nextCursor,
+  })
+}
+
+const getTrailingInlineCaretHelperNode = (): Text | null => {
+  const editor = inlineEditorRef.value
+  if (!editor) {
+    return null
+  }
+  return findLastInlineTextNode(editor.childNodes, isInlineVisualCaretTextNode)
+}
+
+const isCollapsedSelectionAtTrailingInlineCaretHelper = (range: Range): boolean => {
+  const editor = inlineEditorRef.value
+  const helperNode = getTrailingInlineCaretHelperNode()
+  if (!editor || !helperNode || !range.collapsed || !hasTrailingInlineCaretHelper.value) {
+    return false
+  }
+
+  if (range.startContainer === helperNode) {
+    return true
+  }
+
+  if (range.startContainer !== editor) {
+    return false
+  }
+
+  const childNodes = Array.from(editor.childNodes)
+  const helperIndex = childNodes.indexOf(helperNode)
+  return helperIndex >= 0 && range.startOffset === helperIndex + 1
+}
+
+const deleteTrailingInlineLineBreak = (): void => {
+  const editor = inlineEditorRef.value
+  const helperNode = getTrailingInlineCaretHelperNode()
+  if (!editor || !helperNode) {
+    return
+  }
+
+  const childNodes = Array.from(editor.childNodes)
+  const helperIndex = childNodes.indexOf(helperNode)
+  const previousNode = helperIndex > 0 ? childNodes[helperIndex - 1] ?? null : null
+
+  if (!(previousNode instanceof Text) || previousNode.textContent === null || !previousNode.textContent.endsWith('\n')) {
+    throw new Error('Trailing inline caret helper must follow a text node ending with newline.')
+  }
+
+  const nextText = previousNode.textContent.slice(0, -1)
+  helperNode.remove()
+  if (nextText.length === 0) {
+    previousNode.remove()
+  } else {
+    previousNode.textContent = nextText
+  }
+
+  const selection = window.getSelection()
+  if (selection) {
+    const range = document.createRange()
+    range.selectNodeContents(editor)
+    range.collapse(false)
+    selection.removeAllRanges()
+    selection.addRange(range)
+  }
+
+  lastSelectionOffset.value = segmentsToText(readInlineSegmentsFromDom()).length
+  emitInlineSegmentsFromDom()
+}
+
+const getInlineSegmentLogicalLength = (segment: SInlineTokenEditorSegment): number =>
+  segment.kind === 'text' ? segment.text.length : segment.label.length
+
+const splitInlineSegmentsAtOffset = (
+  segments: readonly SInlineTokenEditorSegment[],
+  offset: number,
+): { before: SInlineTokenEditorSegment[]; after: SInlineTokenEditorSegment[] } => {
+  const validatedOffset = validateInlineTokenCursorBoundary(segments, offset, 'split offset')
+  const before: SInlineTokenEditorSegment[] = []
+  const after: SInlineTokenEditorSegment[] = []
+  let cursor = 0
+  let splitDone = false
+
+  for (const segment of segments) {
+    const length = getInlineSegmentLogicalLength(segment)
+    const segmentStart = cursor
+    const segmentEnd = cursor + length
+
+    if (splitDone || validatedOffset <= segmentStart) {
+      after.push(segment)
+      cursor = segmentEnd
+      continue
+    }
+
+    if (validatedOffset >= segmentEnd) {
+      before.push(segment)
+      cursor = segmentEnd
+      continue
+    }
+
+    if (segment.kind === 'text') {
+      const splitIndex = validatedOffset - segmentStart
+      const left = segment.text.slice(0, splitIndex)
+      const right = segment.text.slice(splitIndex)
+      if (left) {
+        before.push({ kind: 'text', text: left })
+      }
+      if (right) {
+        after.push({ kind: 'text', text: right })
+      }
+    } else if (validatedOffset > segmentStart) {
+      before.push(segment)
+    } else {
+      after.push(segment)
+    }
+
+    splitDone = true
+    cursor = segmentEnd
+  }
+
+  return {
+    before: composeInlineTokenSegments(before),
+    after: composeInlineTokenSegments(after),
+  }
+}
+
+const replaceInlineSegmentsRange = (
+  start: number,
+  end: number,
+  replacement: readonly SInlineTokenEditorSegment[],
+): SInlineTokenEditorSegment[] => {
+  const source = inlineSegments.value
+  const validatedStart = validateInlineTokenCursorBoundary(source, start, 'replacement start')
+  const validatedEnd = validateInlineTokenCursorBoundary(source, end, 'replacement end')
+  if (validatedStart > validatedEnd) {
+    throw new RangeError(`SInlineTokenEditor: replacement start ${validatedStart} не может быть больше end ${validatedEnd}. / SInlineTokenEditor: replacement start ${validatedStart} cannot exceed end ${validatedEnd}.`)
+  }
+  const startSplit = splitInlineSegmentsAtOffset(source, validatedStart)
+  const endSplit = splitInlineSegmentsAtOffset(source, validatedEnd)
+  return composeInlineTokenSegments([
+    ...startSplit.before,
+    ...replacement,
+    ...endSplit.after,
+  ])
+}
+
+const resolveInlineSelectionOffsets = (range: Range): { start: number; end: number } | null => {
+  const editor = inlineEditorRef.value
+  if (!editor) {
+    return null
+  }
+
+  const inlineTextLength = segmentsToText(inlineSegments.value).length
+  if (isCollapsedSelectionAtTrailingInlineCaretHelper(range)) {
+    return { start: inlineTextLength, end: inlineTextLength }
+  }
+
+  const resolveBoundary = (container: Node, boundaryOffset: number): number => {
+    if (container === editor && editor.childNodes.length === 0) {
+      validateDomBoundaryOffset(container, boundaryOffset, 'empty editor selection boundary')
+      return 0
+    }
+    return calculateOffsetWithin(editor, container, boundaryOffset)
+  }
+
+  return {
+    start: resolveBoundary(range.startContainer, range.startOffset),
+    end: resolveBoundary(range.endContainer, range.endOffset),
+  }
+}
+
+const deleteInlineBackward = (offset: number): void => {
+  const sourceSegments = inlineSegments.value
+  const validatedOffset = validateInlineTokenCursorBoundary(sourceSegments, offset, 'delete backward offset')
+  if (validatedOffset === 0) {
+    return
+  }
+
+  const source = sourceSegments.map((segment): SInlineTokenEditorSegment => (
+    segment.kind === 'text'
+      ? { kind: 'text', text: segment.text }
+      : {
+        kind: 'token',
+        occurrenceId: segment.occurrenceId,
+        id: segment.id,
+        label: segment.label,
+        ...(segment.title === undefined ? {} : { title: segment.title }),
+      }
+  ))
+
+  let segmentStart = 0
+  for (let index = 0; index < source.length; index += 1) {
+    const segment = source[index]!
+    const segmentEnd = segmentStart + getInlineSegmentLogicalLength(segment)
+
+    if (validatedOffset > segmentEnd) {
+      segmentStart = segmentEnd
+      continue
+    }
+
+    if (segment.kind === 'text') {
+      const deleteIndex = validatedOffset - segmentStart - 1
+      if (deleteIndex < 0 || deleteIndex >= segment.text.length) {
+        throw new RangeError(`SInlineTokenEditor: delete index ${deleteIndex} вне text segment [0, ${segment.text.length - 1}]. / SInlineTokenEditor: delete index ${deleteIndex} is outside text segment [0, ${segment.text.length - 1}].`)
+      }
+      const nextText = `${segment.text.slice(0, deleteIndex)}${segment.text.slice(deleteIndex + 1)}`
+      source[index] = { kind: 'text', text: nextText }
+      commitInlineSegmentsUpdate(source, validatedOffset - 1)
+      return
+    }
+
+    const previous = source[index - 1]
+    const next = source[index + 1]
+    if (
+      previous?.kind === 'text'
+      && next?.kind === 'text'
+      && previous.text.endsWith(' ')
+      && next.text.startsWith(' ')
+    ) {
+      source[index + 1] = { kind: 'text', text: next.text.slice(1) }
+    }
+    source.splice(index, 1)
+    commitInlineSegmentsUpdate(source, segmentStart)
+    return
+  }
+}
+
+const ensureInlineSelectionRange = (allowSyntheticSelection: boolean): Range | null => {
+  const editor = inlineEditorRef.value
+  const selection = window.getSelection()
+  if (!editor || !selection) {
+    return null
+  }
+
+  if (selection.rangeCount > 0) {
+    const range = selection.getRangeAt(0)
+    if (editor.contains(range.startContainer) || range.startContainer === editor) {
+      return range
+    }
+  }
+
+  if (!allowSyntheticSelection) {
+    return null
+  }
+
+  editor.focus()
+  placeInlineSelectionAtOffset(lastSelectionOffset.value)
+  if (selection.rangeCount > 0) {
+    return selection.getRangeAt(0)
+  }
+
+  const range = buildInlineRangeAtOffset(editor, lastSelectionOffset.value)
+  selection.removeAllRanges()
+  selection.addRange(range)
+  return range
+}
+
+const insertPlainTextAtInlineSelection = (
+  text: string,
+  options: { allowSyntheticSelection?: boolean } = {},
+): void => {
+  if (!text || validatedDisabled.value || validatedReadonly.value) return
+
+  const range = ensureInlineSelectionRange(options.allowSyntheticSelection === true)
+  if (!range) {
+    throw new Error('SInlineTokenEditor: active selection отсутствует в editing surface. / SInlineTokenEditor: no active selection exists inside the editing surface.')
+  }
+
+  const offsets = resolveInlineSelectionOffsets(range)
+  if (!offsets) {
+    throw new Error('SInlineTokenEditor: selection offsets недоступны до readiness. / SInlineTokenEditor: selection offsets are unavailable before readiness.')
+  }
+
+  const nextSegments = replaceInlineSegmentsRange(
+    offsets.start,
+    offsets.end,
+    [{ kind: 'text', text }],
+  )
+  commitInlineSegmentsUpdate(nextSegments, offsets.start + text.length)
+}
+
+const insertSoftLineBreak = (): void => {
+  if (validatedDisabled.value || validatedReadonly.value) return
+  insertPlainTextAtInlineSelection('\n', { allowSyntheticSelection: true })
+}
+
+const replaceRange = (replacement: SInlineTokenEditorReplacement): void => {
+  if (validatedDisabled.value || validatedReadonly.value) {
+    throw new Error('SInlineTokenEditor: replaceRange недоступен для disabled или readonly editor. / SInlineTokenEditor: replaceRange is unavailable for a disabled or readonly editor.')
+  }
+  const editor = inlineEditorRef.value
+  if (!editor) {
+    throw new Error('SInlineTokenEditor: editing surface не готова. / SInlineTokenEditor: editing surface is not ready.')
+  }
+  const nextSegments = replaceInlineSegmentsRange(
+    replacement.start,
+    replacement.end,
+    replacement.segments,
+  )
+  editor.focus()
+  commitInlineSegmentsUpdate(nextSegments, replacement.cursor)
+}
+
+defineExpose<SInlineTokenEditorApi>({
+  focus: () => {
+    const editor = inlineEditorRef.value
+    if (!editor) throw new Error('SInlineTokenEditor: editing surface не готова. / SInlineTokenEditor: editing surface is not ready.')
+    editor.focus()
+  },
+  insertSoftLineBreak,
+  getSelectionOffset: getInlineSelectionOffset,
+  queueSelectionOffset: (offset: number) => {
+    pendingInlineSelectionOffset.value = validateBoundedInteger(
+      'SInlineTokenEditor',
+      'queued selection offset',
+      offset,
+      { minimum: 0, maximum: Number.MAX_SAFE_INTEGER },
+    )
+  },
+  setSelectionOffset: (offset: number) => {
+    const nextOffset = validateInlineTokenCursorBoundary(inlineSegments.value, offset, 'imperative selection offset')
+    const editor = inlineEditorRef.value
+    if (!editor) throw new Error('SInlineTokenEditor: editing surface не готова. / SInlineTokenEditor: editing surface is not ready.')
+    if (!window.getSelection()) {
+      throw new Error('SInlineTokenEditor: Selection API недоступен. / SInlineTokenEditor: Selection API is unavailable.')
+    }
+    editor.focus()
+    placeInlineSelectionAtOffset(nextOffset)
+    pendingInlineSelectionOffset.value = nextOffset
+    emit('state-change', {
+      text: segmentsToText(inlineSegments.value),
+      cursor: nextOffset,
+    })
+  },
+  replaceRange,
+})
+
+function handleInlineInput() {
+  if (validatedDisabled.value || validatedReadonly.value) return
+  emitInlineSegmentsFromDom()
+}
+
+function handleInlineBeforeInput(event: InputEvent) {
+  if (validatedDisabled.value || validatedReadonly.value || event.defaultPrevented) return
+  if (event.isComposing) return
+
+  if (event.inputType === 'deleteContentBackward') {
+    const range = ensureInlineSelectionRange(true)
+    if (range && isCollapsedSelectionAtTrailingInlineCaretHelper(range)) {
+      if (inlineTrailingCaretHelperKind.value === 'newline') {
+        event.preventDefault()
+        deleteTrailingInlineLineBreak()
+        return
+      }
+      if (inlineTrailingCaretHelperKind.value === 'token') {
+        event.preventDefault()
+        deleteInlineBackward(getInlineSelectionOffset())
+        return
+      }
+      return
+    }
+    if (range?.collapsed) {
+      event.preventDefault()
+      deleteInlineBackward(getInlineSelectionOffset())
+      return
+    }
+  }
+
+  if (event.inputType === 'insertText' && typeof event.data === 'string' && event.data.length > 0) {
+    event.preventDefault()
+    insertPlainTextAtInlineSelection(event.data, { allowSyntheticSelection: true })
+    return
+  }
+
+  if (event.inputType === 'insertLineBreak' || event.inputType === 'insertParagraph') {
+    event.preventDefault()
+    insertSoftLineBreak()
+  }
+}
+
+function handleInlinePaste(event: ClipboardEvent) {
+  if (validatedDisabled.value || validatedReadonly.value) return
+  event.preventDefault()
+  if (!event.clipboardData) {
+    throw new TypeError('SInlineTokenEditor: paste event не содержит clipboardData. / SInlineTokenEditor: paste event has no clipboardData.')
+  }
+  const text = event.clipboardData.getData('text/plain')
+  insertPlainTextAtInlineSelection(text)
+}
+
+function handleInlineKeydown(event: KeyboardEvent) {
+  emit('keydown', event)
+  if (validatedDisabled.value || validatedReadonly.value || event.defaultPrevented) {
+    return
+  }
+  if (event.key === 'Enter' && event.shiftKey) {
+    event.preventDefault()
+    insertSoftLineBreak()
+    return
+  }
+
+  const normalizedKey = event.key === 'Space' || event.key === 'Spacebar' || event.code === 'Space'
+    ? ' '
+    : event.key
+
+  if (
+    !event.isComposing
+    && !event.ctrlKey
+    && !event.metaKey
+    && !event.altKey
+    && normalizedKey.length === 1
+  ) {
+    event.preventDefault()
+    insertPlainTextAtInlineSelection(normalizedKey, { allowSyntheticSelection: true })
+  }
+}
+
+function handleInlineKeyup(event: KeyboardEvent) {
+  emit('keyup', event)
+  emitInlineEditorState()
+}
+
+function handleInlineClick(event: MouseEvent) {
+  emit('click', event)
+  emitInlineEditorState()
+}
+
+function handleInlineTokenAction(event: InlineTokenActionEvent) {
+  const occurrenceId = validateNonEmptyString(
+    'SInlineTokenEditor', 'token action occurrenceId', event.occurrenceId,
+  )
+  const tokenId = validateNonEmptyString('SInlineTokenEditor', 'token action id', event.id)
+  const reference: SInlineTokenEditorTokenReference = { occurrenceId, id: tokenId }
+  if (event.action === 'open') {
+    if (!validatedDisabled.value) emit('open-token', reference)
+    return
+  }
+  if (validatedDisabled.value || validatedReadonly.value) return
+
+  const source = inlineSegments.value
+  let cursor = 0
+  const nextSegments: SInlineTokenEditorSegment[] = []
+  let removed = false
+  let removeOneLeadingSeparatorSpace = false
+  for (let index = 0; index < source.length; index += 1) {
+    const sourceSegment = source[index]!
+    const segment: SInlineTokenEditorSegment = (
+      removeOneLeadingSeparatorSpace
+      && sourceSegment.kind === 'text'
+      && sourceSegment.text.startsWith(' ')
+    )
+      ? { kind: 'text', text: sourceSegment.text.slice(1) }
+      : sourceSegment
+    removeOneLeadingSeparatorSpace = false
+    if (segment.kind === 'token' && segment.occurrenceId === occurrenceId) {
+      if (segment.id !== tokenId) {
+        throw new TypeError(`SInlineTokenEditor: token action id ${JSON.stringify(tokenId)} does not match occurrence ${JSON.stringify(occurrenceId)}`)
+      }
+      removed = true
+      const previous = nextSegments[nextSegments.length - 1]
+      const upcoming = source[index + 1]
+      if (
+        previous?.kind === 'text'
+        && upcoming?.kind === 'text'
+        && previous.text.endsWith(' ')
+        && upcoming.text.startsWith(' ')
+      ) {
+        removeOneLeadingSeparatorSpace = true
+      }
+      continue
+    }
+    if (!removed) cursor += getInlineSegmentLogicalLength(segment)
+    nextSegments.push(segment)
+  }
+  if (!removed) {
+    throw new RangeError(`SInlineTokenEditor: token action occurrence ${JSON.stringify(occurrenceId)} does not exist`)
+  }
+  emit('remove-token', reference)
+  commitInlineSegmentsUpdate(nextSegments, cursor)
+}
+
+watch(
+  inlineDomSignature,
+  () => {
+    const editor = inlineEditorRef.value
+    if (!editor) return
+    const queuedSelectionOffset = pendingInlineSelectionOffset.value
+    const shouldRestoreSelection = queuedSelectionOffset !== null
+      || document.activeElement === editor
+      || editor.contains(document.activeElement)
+    if (!shouldRestoreSelection) return
+    inlineSelectionOffsetToRestore.value = validateInlineTokenCursorBoundary(
+      inlineSegments.value,
+      queuedSelectionOffset ?? getInlineSelectionOffset(),
+      'retained selection offset',
+    )
+  },
+  { flush: 'pre' },
+)
+
+watch(
+  inlineDomSignature,
+  () => {
+    const selectionOffset = inlineSelectionOffsetToRestore.value
+    if (selectionOffset === null) return
+    placeInlineSelectionAtOffset(validateInlineTokenCursorBoundary(
+      inlineSegments.value,
+      selectionOffset,
+      'restored selection offset',
+    ))
+    inlineSelectionOffsetToRestore.value = null
+    pendingInlineSelectionOffset.value = null
+  },
+  { flush: 'post' },
+)
+</script>