@pgcorp/ui-kit 0.8.1 → 0.10.0

package/src/components/shared/persona/presentation.ts

@@ -1,4 +1,9 @@
 import { validateExactString } from '../../../internal/runtimeContract'
+import type { UiKitLocale, UiKitStaticMessageKey, UiKitTranslate } from '../../../locales/locale'
+import { createUiKitTranslate, UI_KIT_MESSAGES } from '../../../locales/messages'
+
+const defaultTranslate = createUiKitTranslate(() => UI_KIT_MESSAGES.ru)
+type PersonaStaticMessageKey = Extract<UiKitStaticMessageKey, `persona.${string}`>
 
 export type PersonaStatusSeverity = 'secondary' | 'success' | 'info' | 'warn' | 'danger'
 
@@ -31,18 +36,23 @@ type PersonaDiagnosticOverviewItem = {
 
 export function personaDiagnosticPresentation(
   input: PersonaDiagnosticPresentationInput,
+  t: UiKitTranslate = defaultTranslate,
 ): PersonaDiagnosticPresentation {
   const isError = input.severity === 'error' || input.severity === 'blocking'
-  const statusLabel = isError ? 'ошибка' : input.severity === 'warning' ? 'предупреждение' : 'информация'
+  const statusLabel = isError
+    ? t('persona.diagnosticError')
+    : input.severity === 'warning'
+      ? t('persona.diagnosticWarning')
+      : t('persona.diagnosticInformation')
   const statusSeverity: PersonaStatusSeverity = isError ? 'danger' : input.severity === 'warning' ? 'warn' : 'info'
 
   if (input.context === 'native_scenarios') {
     return {
       category: 'scenario_import',
-      title: 'Сценарий не импортирован',
-      ownerLabel: 'Исправить в тестовом проекте',
-      impactLabel: 'Сценарий недоступен для запуска',
-      remediation: 'Восстановить отсутствующий модуль или исправить импорт в сценарии.',
+      title: t('persona.scenarioNotImported'),
+      ownerLabel: t('persona.fixInTestProject'),
+      impactLabel: t('persona.scenarioUnavailable'),
+      remediation: t('persona.restoreScenarioImport'),
       statusLabel,
       statusSeverity,
     }
@@ -50,23 +60,23 @@ export function personaDiagnosticPresentation(
   if (input.context === 'components') {
     return {
       category: 'component_analysis',
-      title: 'Компонент не проанализирован',
-      ownerLabel: 'Исправить в тестовом проекте',
-      impactLabel: 'Структура связанных сценариев может быть неполной',
-      remediation: 'Исправить импорт компонента и его зависимостей.',
+      title: t('persona.componentNotAnalyzed'),
+      ownerLabel: t('persona.fixInTestProject'),
+      impactLabel: t('persona.relatedStructureIncomplete'),
+      remediation: t('persona.restoreComponentImport'),
       statusLabel,
       statusSeverity,
     }
   }
   if (input.context === 'support_quality') {
     const remediation = input.reason === 'page_support_import_non_maintained'
-      ? 'Перенести используемый PageObject из пробной области в поддерживаемую область проекта.'
-      : 'Дать элементу или компоненту устойчивое предметное имя в коде проекта.'
+      ? t('persona.movePageObject')
+      : t('persona.giveStableName')
     return {
       category: 'support_quality',
-      title: 'Качество PageObject',
-      ownerLabel: 'Исправить в тестовом проекте',
-      impactLabel: 'Не блокирует доступные сценарии',
+      title: t('persona.pageObjectQuality'),
+      ownerLabel: t('persona.fixInTestProject'),
+      impactLabel: t('persona.doesNotBlockScenarios'),
       remediation,
       statusLabel,
       statusSeverity,
@@ -74,10 +84,10 @@ export function personaDiagnosticPresentation(
   }
   return {
     category: 'unclassified',
-    title: 'Неклассифицированное сообщение Persona',
-    ownerLabel: 'Требуется классификация Persona',
-    impactLabel: 'Влияние не указано',
-    remediation: 'Persona должна передать машинно-читаемые владельца, влияние и способ исправления.',
+    title: t('persona.unclassifiedPersonaMessage'),
+    ownerLabel: t('persona.personaClassificationRequired'),
+    impactLabel: t('persona.impactUnspecified'),
+    remediation: t('persona.personaMustClassify'),
     statusLabel,
     statusSeverity,
   }
@@ -87,6 +97,7 @@ export function personaDiagnosticOverviewMessage(
   availableTests: number,
   unavailableTests: number,
   diagnostics: readonly PersonaDiagnosticOverviewItem[],
+  t: UiKitTranslate = defaultTranslate,
 ): string {
   const count = (category: PersonaDiagnosticOverviewItem['category']) => (
     diagnostics.filter((diagnostic) => diagnostic.category === category).length
@@ -96,12 +107,12 @@ export function personaDiagnosticOverviewMessage(
   const componentAnalysis = count('component_analysis')
   const supportQuality = count('support_quality')
   const parts = [
-    `Доступно ${availableTests} из ${totalTests} сценариев.`,
-    scenarioImports > 0 ? `${scenarioImports} сценариев не импортируются из-за ошибок в зависимостях тестового проекта.` : null,
+    t('persona.overviewAvailable', { available: availableTests, total: totalTests }),
+    scenarioImports > 0 ? t('persona.overviewScenarioImports', { count: scenarioImports }) : null,
     componentAnalysis > 0
-      ? `${componentAnalysis} сообщений относятся к анализу компонентов, остановленному отсутствующими модулями тестового проекта.`
+      ? t('persona.overviewComponentAnalysis', { count: componentAnalysis })
       : null,
-    supportQuality > 0 ? `${supportQuality} замечаний качества PageObject не блокируют доступные сценарии.` : null,
+    supportQuality > 0 ? t('persona.overviewSupportQuality', { count: supportQuality }) : null,
   ]
   return parts.filter((part): part is string => Boolean(part)).join(' ')
 }
@@ -126,24 +137,24 @@ const PERSONA_RUN_STATUSES = [
 ] as const
 type PersonaRunStatus = typeof PERSONA_RUN_STATUSES[number]
 const PERSONA_RUN_STATUS_PRESENTATIONS = {
-  cancelled: { label: 'отменён', severity: 'secondary' },
-  cancelling: { label: 'отменяется', severity: 'warn' },
-  completed: { label: 'завершён', severity: 'success' },
-  degraded: { label: 'требует внимания', severity: 'warn' },
-  error: { label: 'ошибка', severity: 'danger' },
-  failed: { label: 'ошибка', severity: 'danger' },
-  passed: { label: 'пройден', severity: 'success' },
-  paused: { label: 'приостановлен', severity: 'info' },
-  queued: { label: 'в очереди', severity: 'warn' },
-  running: { label: 'выполняется', severity: 'info' },
-  skipped: { label: 'пропущен', severity: 'warn' },
-  timed_out: { label: 'превышено время', severity: 'danger' },
-  timeout: { label: 'превышено время', severity: 'danger' },
-  info: { label: 'информация', severity: 'info' },
-  warn: { label: 'предупреждение', severity: 'warn' },
-  warning: { label: 'предупреждение', severity: 'warn' },
+  cancelled: { labelKey: 'persona.statusCancelled', severity: 'secondary' },
+  cancelling: { labelKey: 'persona.statusCancelling', severity: 'warn' },
+  completed: { labelKey: 'persona.statusCompleted', severity: 'success' },
+  degraded: { labelKey: 'persona.statusDegraded', severity: 'warn' },
+  error: { labelKey: 'persona.statusError', severity: 'danger' },
+  failed: { labelKey: 'persona.statusError', severity: 'danger' },
+  passed: { labelKey: 'persona.statusPassed', severity: 'success' },
+  paused: { labelKey: 'persona.statusPaused', severity: 'info' },
+  queued: { labelKey: 'persona.statusQueued', severity: 'warn' },
+  running: { labelKey: 'persona.statusRunning', severity: 'info' },
+  skipped: { labelKey: 'persona.statusSkipped', severity: 'warn' },
+  timed_out: { labelKey: 'persona.statusTimedOut', severity: 'danger' },
+  timeout: { labelKey: 'persona.statusTimedOut', severity: 'danger' },
+  info: { labelKey: 'persona.diagnosticInformation', severity: 'info' },
+  warn: { labelKey: 'persona.diagnosticWarning', severity: 'warn' },
+  warning: { labelKey: 'persona.diagnosticWarning', severity: 'warn' },
 } as const satisfies Record<PersonaRunStatus, {
-  label: string
+  labelKey: PersonaStaticMessageKey
   severity: PersonaStatusSeverity
 }>
 
@@ -151,8 +162,8 @@ function resolvePersonaRunStatus(status: unknown): PersonaRunStatus {
   return validateExactString('Persona presentation', 'run status', status, PERSONA_RUN_STATUSES)
 }
 
-export function personaRunStatusLabel(status: unknown): string {
-  return PERSONA_RUN_STATUS_PRESENTATIONS[resolvePersonaRunStatus(status)].label
+export function personaRunStatusLabel(status: unknown, t: UiKitTranslate = defaultTranslate): string {
+  return t(PERSONA_RUN_STATUS_PRESENTATIONS[resolvePersonaRunStatus(status)].labelKey)
 }
 
 export function personaStatusSeverity(status: unknown): PersonaStatusSeverity {
@@ -180,26 +191,26 @@ const PERSONA_SEMANTIC_KINDS = [
 ] as const
 type PersonaSemanticKind = typeof PERSONA_SEMANTIC_KINDS[number]
 const PERSONA_SEMANTIC_KIND_LABELS = {
-    Action: 'Действие',
-    CombinedStep: 'Составной шаг',
-    Expectation: 'Проверка',
-    Fact: 'Данные',
-    Goal: 'Цель',
-    Ops: 'Служебная операция',
-    Step: 'Шаг',
-    action: 'Действие',
-    check: 'Проверка',
-    combined_step: 'Составной шаг',
-    expectation: 'Проверка',
-    fact: 'Данные',
-    get: 'Получение данных',
-    goal: 'Цель',
-    make: 'Действие',
-    persona_call: 'Вызов Persona',
-    step: 'Шаг',
-} as const satisfies Record<PersonaSemanticKind, string>
+  Action: 'persona.semanticAction',
+  CombinedStep: 'persona.semanticCombinedStep',
+  Expectation: 'persona.semanticExpectation',
+  Fact: 'persona.semanticFact',
+  Goal: 'persona.semanticGoal',
+  Ops: 'persona.semanticOps',
+  Step: 'persona.semanticStep',
+  action: 'persona.semanticAction',
+  check: 'persona.semanticExpectation',
+  combined_step: 'persona.semanticCombinedStep',
+  expectation: 'persona.semanticExpectation',
+  fact: 'persona.semanticFact',
+  get: 'persona.semanticGet',
+  goal: 'persona.semanticGoal',
+  make: 'persona.semanticAction',
+  persona_call: 'persona.semanticPersonaCall',
+  step: 'persona.semanticStep',
+} as const satisfies Record<PersonaSemanticKind, PersonaStaticMessageKey>
 
-export function personaSemanticKindLabel(kind: unknown): string {
+export function personaSemanticKindLabel(kind: unknown, t: UiKitTranslate = defaultTranslate): string {
   if (kind === null || kind === undefined) return ''
   const resolvedKind = validateExactString(
     'Persona presentation',
@@ -207,30 +218,33 @@ export function personaSemanticKindLabel(kind: unknown): string {
     kind,
     PERSONA_SEMANTIC_KINDS,
   )
-  return PERSONA_SEMANTIC_KIND_LABELS[resolvedKind]
+  return t(PERSONA_SEMANTIC_KIND_LABELS[resolvedKind])
 }
 
-export function personaParameterSummary(parameters: readonly PersonaParameterPresentation[]): string {
+export function personaParameterSummary(
+  parameters: readonly PersonaParameterPresentation[],
+  t: UiKitTranslate = defaultTranslate,
+): string {
   return parameters.map((parameter) => {
     const type = parameter.type ? `: ${parameter.type}` : ''
     const hasPrimitiveDefault = typeof parameter.default === 'string'
       || typeof parameter.default === 'number'
       || typeof parameter.default === 'boolean'
     const defaultValue = hasPrimitiveDefault ? ` = ${String(parameter.default)}` : ''
-    return `${parameter.name}${type}${defaultValue}${parameter.required ? ' (обязательный)' : ''}`
+    return `${parameter.name}${type}${defaultValue}${parameter.required ? ` (${t('persona.requiredParameter')})` : ''}`
   }).join(', ')
 }
 
 const PERSONA_SEVERITIES = ['blocker', 'critical', 'minor', 'normal', 'trivial'] as const
 type PersonaSeverity = typeof PERSONA_SEVERITIES[number]
 const PERSONA_SEVERITY_PRESENTATIONS = {
-  blocker: { label: 'блокирующий', severity: 'danger' },
-  critical: { label: 'критический', severity: 'danger' },
-  minor: { label: 'низкая критичность', severity: 'secondary' },
-  normal: { label: 'обычная критичность', severity: 'info' },
-  trivial: { label: 'минимальная критичность', severity: 'secondary' },
+  blocker: { labelKey: 'persona.severityBlocker', severity: 'danger' },
+  critical: { labelKey: 'persona.severityCritical', severity: 'danger' },
+  minor: { labelKey: 'persona.severityMinor', severity: 'secondary' },
+  normal: { labelKey: 'persona.severityNormal', severity: 'info' },
+  trivial: { labelKey: 'persona.severityTrivial', severity: 'secondary' },
 } as const satisfies Record<PersonaSeverity, {
-  label: string
+  labelKey: PersonaStaticMessageKey
   severity: PersonaStatusSeverity
 }>
 
@@ -238,8 +252,8 @@ function resolvePersonaSeverity(value: unknown): PersonaSeverity {
   return validateExactString('Persona presentation', 'severity', value, PERSONA_SEVERITIES)
 }
 
-export function personaSeverityLabel(value: unknown): string {
-  return PERSONA_SEVERITY_PRESENTATIONS[resolvePersonaSeverity(value)].label
+export function personaSeverityLabel(value: unknown, t: UiKitTranslate = defaultTranslate): string {
+  return t(PERSONA_SEVERITY_PRESENTATIONS[resolvePersonaSeverity(value)].labelKey)
 }
 
 export function personaSeverityBadge(value: unknown): PersonaStatusSeverity {
@@ -249,20 +263,20 @@ export function personaSeverityBadge(value: unknown): PersonaStatusSeverity {
 const PERSONA_REPORT_STATUSES = ['broken', 'failed', 'passed', 'skipped'] as const
 type PersonaReportStatus = typeof PERSONA_REPORT_STATUSES[number]
 const PERSONA_REPORT_STATUS_LABELS = {
-    broken: 'сломан',
-    failed: 'ошибка',
-    passed: 'пройден',
-    skipped: 'пропущен',
-} as const satisfies Record<PersonaReportStatus, string>
+  broken: 'persona.reportBroken',
+  failed: 'persona.statusError',
+  passed: 'persona.statusPassed',
+  skipped: 'persona.statusSkipped',
+} as const satisfies Record<PersonaReportStatus, PersonaStaticMessageKey>
 
-export function personaReportStatusLabel(status: unknown): string {
+export function personaReportStatusLabel(status: unknown, t: UiKitTranslate = defaultTranslate): string {
   const resolvedStatus = validateExactString(
     'Persona presentation',
     'report status',
     status,
     PERSONA_REPORT_STATUSES,
   )
-  return PERSONA_REPORT_STATUS_LABELS[resolvedStatus]
+  return t(PERSONA_REPORT_STATUS_LABELS[resolvedStatus])
 }
 
 const PERSONA_LIFECYCLE_STAGES = [
@@ -273,20 +287,20 @@ const PERSONA_LIFECYCLE_STAGES = [
 ] as const
 type PersonaLifecycleStage = typeof PERSONA_LIFECYCLE_STAGES[number]
 const PERSONA_LIFECYCLE_STAGE_LABELS = {
-    run_after_scenario: 'после сценария',
-    run_after_test: 'после теста',
-    run_before_scenario: 'перед сценарием',
-    run_before_test: 'перед тестом',
-} as const satisfies Record<PersonaLifecycleStage, string>
+  run_after_scenario: 'persona.lifecycleAfterScenario',
+  run_after_test: 'persona.lifecycleAfterTest',
+  run_before_scenario: 'persona.lifecycleBeforeScenario',
+  run_before_test: 'persona.lifecycleBeforeTest',
+} as const satisfies Record<PersonaLifecycleStage, PersonaStaticMessageKey>
 
-export function personaLifecycleStageLabel(stage: unknown): string {
+export function personaLifecycleStageLabel(stage: unknown, t: UiKitTranslate = defaultTranslate): string {
   const resolvedStage = validateExactString(
     'Persona presentation',
     'lifecycle stage',
     stage,
     PERSONA_LIFECYCLE_STAGES,
   )
-  return PERSONA_LIFECYCLE_STAGE_LABELS[resolvedStage]
+  return t(PERSONA_LIFECYCLE_STAGE_LABELS[resolvedStage])
 }
 
 const PERSONA_EVENT_TYPES = [
@@ -308,31 +322,31 @@ const PERSONA_EVENT_TYPES = [
 ] as const
 type PersonaEventType = typeof PERSONA_EVENT_TYPES[number]
 const PERSONA_EVENT_TYPE_LABELS = {
-    cancelled: 'Запуск отменён',
-    completed: 'Запуск завершён',
-    failed: 'Запуск завершён с ошибкой',
-    log: 'Сообщение выполнения',
-    queued: 'Запуск поставлен в очередь',
-    running: 'Запуск начат',
-    started: 'Запуск начат',
-    timeout: 'Время запуска превышено',
-    'report.runtime_log': 'Сообщение выполнения',
-    'scenario.accepted': 'Тест поставлен в очередь',
-    'scenario.cancelled': 'Тест отменён',
-    'scenario.finished': 'Тест завершён',
-    'scenario.started': 'Тест запущен',
-    'worker.started': 'Исполнитель подключён',
-    'worker.stopped': 'Исполнитель остановлен',
-} as const satisfies Record<PersonaEventType, string>
+  cancelled: 'persona.eventRunCancelled',
+  completed: 'persona.eventRunCompleted',
+  failed: 'persona.eventRunFailed',
+  log: 'persona.eventRuntimeMessage',
+  queued: 'persona.eventRunQueued',
+  running: 'persona.eventRunStarted',
+  started: 'persona.eventRunStarted',
+  timeout: 'persona.eventRunTimedOut',
+  'report.runtime_log': 'persona.eventRuntimeMessage',
+  'scenario.accepted': 'persona.eventTestQueued',
+  'scenario.cancelled': 'persona.eventTestCancelled',
+  'scenario.finished': 'persona.eventTestFinished',
+  'scenario.started': 'persona.eventTestStarted',
+  'worker.started': 'persona.eventWorkerStarted',
+  'worker.stopped': 'persona.eventWorkerStopped',
+} as const satisfies Record<PersonaEventType, PersonaStaticMessageKey>
 
-export function personaEventTypeLabel(eventType: unknown): string {
+export function personaEventTypeLabel(eventType: unknown, t: UiKitTranslate = defaultTranslate): string {
   const resolvedEventType = validateExactString(
     'Persona presentation',
     'event type',
     eventType,
     PERSONA_EVENT_TYPES,
   )
-  return PERSONA_EVENT_TYPE_LABELS[resolvedEventType]
+  return t(PERSONA_EVENT_TYPE_LABELS[resolvedEventType])
 }
 
 export function personaPayloadMessage(payload: Record<string, unknown> | null): string {
@@ -344,20 +358,36 @@ export function personaPayloadMessage(payload: Record<string, unknown> | null):
   return ''
 }
 
-export function personaDistinctMessage(title: string, message: string | null | undefined): string | null {
+export function personaDistinctMessage(
+  title: string,
+  message: string | null | undefined,
+  locale: UiKitLocale = 'ru',
+): string | null {
   const normalizedMessage = message?.trim()
   if (!normalizedMessage) return null
-  const comparable = (value: string) => value.toLocaleLowerCase('ru-RU').replace(/[.!?]+$/u, '').trim()
+  const comparable = (value: string) => value.toLocaleLowerCase(locale).replace(/[.!?]+$/u, '').trim()
   return comparable(title) === comparable(normalizedMessage) ? null : normalizedMessage
 }
 
-export function personaDurationLabel(durationMs: number | null | undefined): string {
-  if (durationMs === null || durationMs === undefined) return 'длительность не определена'
-  if (durationMs < 1000) return `${durationMs} мс`
-  return `${(durationMs / 1000).toLocaleString('ru-RU', { maximumFractionDigits: 2 })} с`
+export function personaDurationLabel(
+  durationMs: number | null | undefined,
+  t: UiKitTranslate = defaultTranslate,
+  locale: UiKitLocale = 'ru',
+): string {
+  if (durationMs === null || durationMs === undefined) return t('persona.durationUnknown')
+  if (durationMs < 1000) return t('persona.durationMilliseconds', { value: durationMs })
+  return t('persona.durationSeconds', {
+    value: (durationMs / 1000).toLocaleString(locale, { maximumFractionDigits: 2 }),
+  })
 }
 
-export function personaCountLabel(count: number, forms: [string, string, string]): string {
+export function personaCountLabel(
+  count: number,
+  forms: [string, string, string],
+  locale: UiKitLocale = 'ru',
+): string {
+  if (locale === 'en') return `${count} ${count === 1 ? forms[0] : forms[2]}`
+  if (locale === 'zh-CN' || locale === 'zh-TW') return `${count} ${forms[2]}`
   const remainder100 = count % 100
   const remainder10 = count % 10
   const form = remainder100 >= 11 && remainder100 <= 14

package/src/composables/useFloatingPosition.ts

@@ -15,6 +15,7 @@ export interface FloatingPositionOptions {
   boundaryPadding?: () => number
   flip?: () => boolean
   shift?: () => boolean
+  constrainMainAxis?: () => boolean
   widthMatch?: () => FloatingWidthMatch
   zIndex?: () => string
   scrollStrategy?: 'reposition' | 'close'
@@ -141,9 +142,44 @@ export function useFloatingPosition(options: FloatingPositionOptions): FloatingP
       }
     }
 
+    let positionedPanelWidth = panelWidth
+    let positionedPanelHeight = panelHeight
+    const constrainedStyle: Record<string, string> = {}
+    if (options.constrainMainAxis?.() ?? false) {
+      if (side === 'top' || side === 'bottom') {
+        const availableHeight = side === 'top'
+          ? anchor.top - offset - padding
+          : viewportHeight - padding - anchor.bottom - offset
+        positionedPanelHeight = Math.min(panelHeight, Math.max(0, Math.floor(availableHeight)))
+        constrainedStyle.maxHeight = `${positionedPanelHeight}px`
+        constrainedStyle.overflowY = 'auto'
+      } else {
+        const availableWidth = side === 'left'
+          ? anchor.left - offset - padding
+          : viewportWidth - padding - anchor.right - offset
+        positionedPanelWidth = Math.min(panelWidth, Math.max(0, Math.floor(availableWidth)))
+        constrainedStyle.maxWidth = `${positionedPanelWidth}px`
+        constrainedStyle.overflowX = 'auto'
+      }
+      coordinates = coordinatesFor(
+        side,
+        alignment,
+        anchor,
+        positionedPanelWidth,
+        positionedPanelHeight,
+        offset,
+      )
+    }
+
     if (options.shift?.() ?? true) {
-      coordinates.left = Math.max(padding, Math.min(coordinates.left, viewportWidth - panelWidth - padding))
-      coordinates.top = Math.max(padding, Math.min(coordinates.top, viewportHeight - panelHeight - padding))
+      coordinates.left = Math.max(
+        padding,
+        Math.min(coordinates.left, viewportWidth - positionedPanelWidth - padding),
+      )
+      coordinates.top = Math.max(
+        padding,
+        Math.min(coordinates.top, viewportHeight - positionedPanelHeight - padding),
+      )
     }
 
     const placement = `${side}-${alignment}` as FloatingPlacement
@@ -158,6 +194,7 @@ export function useFloatingPosition(options: FloatingPositionOptions): FloatingP
       left: `${resolvedCoordinates.value.left}px`,
       top: `${resolvedCoordinates.value.top}px`,
       zIndex: options.zIndex?.() ?? 'var(--s-layer-root-floating)',
+      ...constrainedStyle,
       ...(widthMatch === 'min' ? { minWidth: `${Math.round(anchor.width)}px` } : {}),
       ...(widthMatch === 'exact' ? { width: `${Math.round(anchor.width)}px` } : {}),
     }

package/src/composables/useUiKitLocale.ts

@@ -0,0 +1,17 @@
+import { resolveUiKitLocaleContext, type UiKitLocaleContext } from '../internal/localeContext'
+
+/** Returns the immutable locale contract scoped to the current Vue application subtree. */
+export function useUiKitLocale(): UiKitLocaleContext {
+  return resolveUiKitLocaleContext()
+}
+
+export type {
+  UiKitLocale,
+  UiKitMessageKey,
+  UiKitMessageParameters,
+  UiKitMessages,
+  UiKitMessagesOverride,
+  UiKitTranslate,
+} from '../locales/locale'
+export { UI_KIT_LOCALES } from '../locales/locale'
+export { UI_KIT_MESSAGES, UI_KIT_MESSAGE_KEYS } from '../locales/messages'

package/src/internal/codeHighlight.ts

@@ -0,0 +1,110 @@
+import hljs from 'highlight.js/lib/core'
+import bash from 'highlight.js/lib/languages/bash'
+import dockerfile from 'highlight.js/lib/languages/dockerfile'
+import javascript from 'highlight.js/lib/languages/javascript'
+import makefile from 'highlight.js/lib/languages/makefile'
+import nginx from 'highlight.js/lib/languages/nginx'
+import powershell from 'highlight.js/lib/languages/powershell'
+import python from 'highlight.js/lib/languages/python'
+import typescript from 'highlight.js/lib/languages/typescript'
+import xml from 'highlight.js/lib/languages/xml'
+import yaml from 'highlight.js/lib/languages/yaml'
+
+import type { CodeEditorLanguageContract } from './codeEditorContract'
+import { resolveCodeLanguageKey } from './codeLanguageIdentity'
+
+export type CodeHighlightToken = string | {
+  readonly scope: string | null
+  readonly children: readonly CodeHighlightToken[]
+}
+
+const HIGHLIGHT_LANGUAGE_ALIASES: Readonly<Record<string, string>> = {
+  shell: 'bash',
+  text: 'plaintext',
+}
+
+const SAFE_SCOPE_PATTERN = /^[a-z][a-z0-9_.-]*$/u
+
+hljs.registerLanguage('bash', bash)
+hljs.registerLanguage('dockerfile', dockerfile)
+hljs.registerLanguage('javascript', javascript)
+hljs.registerLanguage('makefile', makefile)
+hljs.registerLanguage('nginx', nginx)
+hljs.registerLanguage('powershell', powershell)
+hljs.registerLanguage('python', python)
+hljs.registerLanguage('typescript', typescript)
+hljs.registerLanguage('xml', xml)
+hljs.registerLanguage('yaml', yaml)
+
+function escapeHighlightedCode(code: string): string {
+  return code
+    .replace(/&/gu, '&amp;')
+    .replace(/</gu, '&lt;')
+    .replace(/>/gu, '&gt;')
+    .replace(/"/gu, '&quot;')
+    .replace(/'/gu, '&#39;')
+}
+
+function resolveHighlightLanguage(language: CodeEditorLanguageContract): string {
+  const languageKey = resolveCodeLanguageKey(language)
+  return HIGHLIGHT_LANGUAGE_ALIASES[languageKey] ?? languageKey
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function readTokenNode(value: unknown, coordinate: string): CodeHighlightToken {
+  if (typeof value === 'string') return value
+  if (!isRecord(value)) throw new TypeError(`codeHighlight: ${coordinate} must be a token node or string.`)
+  const unexpected = Object.keys(value).filter((key) => !['scope', 'children', 'language'].includes(key))
+  if (unexpected.length > 0) {
+    throw new TypeError(`codeHighlight: ${coordinate} contains unknown fields ${unexpected.join(', ')}.`)
+  }
+  const rawScope = value.scope
+  if (rawScope !== undefined && (typeof rawScope !== 'string' || !SAFE_SCOPE_PATTERN.test(rawScope))) {
+    throw new TypeError(`codeHighlight: ${coordinate}.scope is invalid.`)
+  }
+  if (!Array.isArray(value.children)) {
+    throw new TypeError(`codeHighlight: ${coordinate}.children must be an array.`)
+  }
+  return Object.freeze({
+    scope: rawScope ?? null,
+    children: Object.freeze(value.children.map((child, index) => readTokenNode(child, `${coordinate}.children[${index}]`))),
+  })
+}
+
+function highlightResult(code: string, language: CodeEditorLanguageContract) {
+  const resolvedLanguage = resolveHighlightLanguage(language)
+  if (!hljs.getLanguage(resolvedLanguage)) return null
+  return hljs.highlight(code, { language: resolvedLanguage, ignoreIllegals: true })
+}
+
+export function isCodeHighlightLanguageSupported(language: CodeEditorLanguageContract): boolean {
+  return Boolean(hljs.getLanguage(resolveHighlightLanguage(language)))
+}
+
+/** Returns trusted library markup only for the legacy sanitized-document pipeline. */
+export function highlightCodeToHtml(code: string, language: CodeEditorLanguageContract): string {
+  return highlightResult(code, language)?.value ?? escapeHighlightedCode(code)
+}
+
+/** Converts the Highlight.js emitter boundary into a closed, validated token tree without HTML rendering. */
+export function highlightCodeToTokens(
+  code: string,
+  language: CodeEditorLanguageContract,
+): readonly CodeHighlightToken[] {
+  const result = highlightResult(code, language)
+  if (result === null) return Object.freeze([code])
+  const root = Reflect.get(result._emitter, 'root')
+  const validated = readTokenNode(root, 'root')
+  if (typeof validated === 'string') {
+    throw new TypeError('codeHighlight: emitter root must be a token node.')
+  }
+  return validated.children
+}
+
+export function highlightScopeClass(scope: string): string {
+  if (!SAFE_SCOPE_PATTERN.test(scope)) throw new TypeError(`codeHighlight: invalid scope ${JSON.stringify(scope)}.`)
+  return `hljs-${scope.replace(/\./gu, '_')}`
+}