@pgcorp/ui-kit 0.9.0 → 0.10.0

package/src/components/shared/data-display/_internal/SRichMath.vue

@@ -0,0 +1,102 @@
+<template>
+  <component
+    :is="validatedDisplay === 'block' ? 'div' : 'span'"
+    class="s-rich-math"
+    :data-display="validatedDisplay"
+    :data-state="state"
+  >
+    <span ref="surface" class="s-rich-math__surface" />
+    <code v-if="state === 'loading'" class="s-rich-math__fallback">{{ validatedSource }}</code>
+    <span v-if="state === 'loading'" class="s-rich-math__assistive" role="status">{{ t('editor.mathLoading') }}</span>
+    <span v-if="state === 'error'" class="s-rich-math__error" role="alert">
+      <span>{{ t('editor.mathError') }}</span>
+      <code>{{ validatedSource }}</code>
+    </span>
+  </component>
+</template>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import 'katex/dist/katex.min.css'
+
+import { useUiKitLocale } from '../../../../composables/useUiKitLocale'
+import { validateExactString, validateNonEmptyString } from '../../../../internal/runtimeContract'
+
+defineOptions({ inheritAttrs: false })
+
+const props = withDefaults(defineProps<{
+  source: string
+  display?: 'inline' | 'block'
+  label?: string
+}>(), {
+  display: 'inline',
+  label: undefined,
+})
+
+const { t } = useUiKitLocale()
+const surface = ref<HTMLElement | null>(null)
+const state = ref<'loading' | 'ready' | 'error'>('loading')
+const validatedSource = computed(() => validateNonEmptyString('SRichMath', 'source', props.source))
+const validatedDisplay = computed(() => validateExactString(
+  'SRichMath',
+  'display',
+  props.display,
+  ['inline', 'block'] as const,
+))
+const validatedLabel = computed(() => props.label === undefined
+  ? validatedSource.value
+  : validateNonEmptyString('SRichMath', 'label', props.label))
+let mounted = false
+let generation = 0
+
+async function renderMath(): Promise<void> {
+  if (!mounted) return
+  const target = surface.value
+  if (!target) throw new Error('SRichMath: render surface is unavailable.')
+  const currentGeneration = generation += 1
+  state.value = 'loading'
+  target.replaceChildren()
+  try {
+    const katex = await import('katex')
+    if (currentGeneration !== generation || !mounted) return
+    katex.default.render(validatedSource.value, target, {
+      displayMode: validatedDisplay.value === 'block',
+      output: 'htmlAndMathml',
+      strict: 'error',
+      throwOnError: true,
+      trust: false,
+      maxExpand: 1_000,
+      maxSize: 20,
+    })
+    target.setAttribute('role', 'math')
+    target.setAttribute('aria-label', validatedLabel.value)
+    state.value = 'ready'
+  } catch {
+    if (currentGeneration !== generation || !mounted) return
+    target.replaceChildren()
+    target.removeAttribute('role')
+    target.removeAttribute('aria-label')
+    state.value = 'error'
+  }
+}
+
+onMounted(() => {
+  mounted = true
+  void renderMath()
+})
+
+watch(
+  () => [props.source, props.display, props.label] as const,
+  () => { void renderMath() },
+)
+
+onBeforeUnmount(() => {
+  mounted = false
+  generation += 1
+  surface.value?.replaceChildren()
+  surface.value?.removeAttribute('role')
+  surface.value?.removeAttribute('aria-label')
+})
+</script>
+
+<style lang="postcss" src="./SRichMath.css"></style>

package/src/components/shared/data-display/codeEditor.ts

@@ -0,0 +1,200 @@
+import {
+  validateBoolean,
+  validateBoundedInteger,
+  validateExactString,
+  validateNonEmptyString,
+} from '../../../internal/runtimeContract'
+
+/** Serializable half-open document range. */
+export interface SCodeEditorRange {
+  readonly from: number
+  readonly to: number
+}
+
+/** Serializable primary selection. Direction is preserved through anchor/head. */
+export interface SCodeEditorSelectionRange extends SCodeEditorRange {
+  readonly anchor: number
+  readonly head: number
+  readonly empty: boolean
+}
+
+/** Selection snapshot returned only through an explicit consumer action. */
+export interface SCodeEditorSelectionSnapshot extends SCodeEditorSelectionRange {
+  readonly text: string
+}
+
+/** Serializable editor view state without a CodeMirror object or DOM reference. */
+export interface SCodeEditorViewState {
+  readonly selection: SCodeEditorSelectionRange
+  readonly scrollTop: number
+  readonly scrollLeft: number
+}
+
+/** Serializable imperative surface; CodeMirror objects and DOM nodes never cross the public boundary. */
+export interface SCodeEditorApi {
+  applySelection(position: number): void
+  revealRange(range: SCodeEditorRange): void
+  getSelection(): SCodeEditorSelectionSnapshot
+  captureViewState(): SCodeEditorViewState
+  applyViewState(viewState: SCodeEditorViewState): void
+  focus(): void
+}
+
+export const S_CODE_EDITOR_DIAGNOSTIC_SEVERITIES = ['error', 'warning', 'info', 'hint'] as const
+export type SCodeEditorDiagnosticSeverity = (typeof S_CODE_EDITOR_DIAGNOSTIC_SEVERITIES)[number]
+export type SCodeEditorDiagnosticId = string | number
+
+/** Controlled diagnostic record rendered by SCodeEditor. */
+export interface SCodeEditorDiagnostic<Id extends SCodeEditorDiagnosticId = string> extends SCodeEditorRange {
+  readonly id: Id
+  readonly severity: SCodeEditorDiagnosticSeverity
+  readonly message: string
+  readonly source?: string
+  readonly code?: string | number
+}
+
+const RANGE_KEYS = new Set(['from', 'to'])
+const SELECTION_KEYS = new Set(['anchor', 'head', 'from', 'to', 'empty'])
+const VIEW_STATE_KEYS = new Set(['selection', 'scrollTop', 'scrollLeft'])
+const DIAGNOSTIC_KEYS = new Set(['id', 'severity', 'message', 'from', 'to', 'source', 'code'])
+
+function assertPlainExactRecord(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+  allowed: ReadonlySet<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 unknownFields = Object.keys(record).filter((key) => !allowed.has(key))
+  if (unknownFields.length > 0) {
+    throw new TypeError(
+      `${owner}.${coordinate}: неизвестные поля ${unknownFields.map((key) => JSON.stringify(key)).join(', ')}. `
+      + `/ ${owner}.${coordinate}: unknown fields ${unknownFields.map((key) => JSON.stringify(key)).join(', ')}.`,
+    )
+  }
+  return record
+}
+
+function validateNonNegativeFiniteNumber(owner: string, coordinate: string, value: unknown): number {
+  if (typeof value === 'number' && Number.isFinite(value) && value >= 0) return value
+  throw new TypeError(
+    `${owner}: ${coordinate} должен быть конечным неотрицательным числом. `
+    + `/ ${owner}: ${coordinate} must be a finite non-negative number.`,
+  )
+}
+
+function validateDiagnosticId(owner: string, coordinate: string, value: unknown): SCodeEditorDiagnosticId {
+  if (typeof value === 'string') return validateNonEmptyString(owner, coordinate, value)
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  throw new TypeError(
+    `${owner}: ${coordinate} должен быть непустой строкой или конечным числом. `
+    + `/ ${owner}: ${coordinate} must be a non-empty string or finite number.`,
+  )
+}
+
+/** Validates a half-open range against the current document without clamping. */
+export function validateCodeEditorRange(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+  documentLength: number,
+): SCodeEditorRange {
+  const length = validateBoundedInteger(owner, 'documentLength', documentLength, {
+    minimum: 0,
+    maximum: Number.MAX_SAFE_INTEGER,
+  })
+  const record = assertPlainExactRecord(owner, coordinate, value, RANGE_KEYS)
+  const from = validateBoundedInteger(owner, `${coordinate}.from`, record.from, { minimum: 0, maximum: length })
+  const to = validateBoundedInteger(owner, `${coordinate}.to`, record.to, { minimum: from, maximum: length })
+  return Object.freeze({ from, to })
+}
+
+/** Validates the primary selection and its derived invariants. */
+export function validateCodeEditorSelectionRange(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+  documentLength: number,
+): SCodeEditorSelectionRange {
+  const record = assertPlainExactRecord(owner, coordinate, value, SELECTION_KEYS)
+  const anchor = validateBoundedInteger(owner, `${coordinate}.anchor`, record.anchor, {
+    minimum: 0,
+    maximum: documentLength,
+  })
+  const head = validateBoundedInteger(owner, `${coordinate}.head`, record.head, {
+    minimum: 0,
+    maximum: documentLength,
+  })
+  const expectedFrom = Math.min(anchor, head)
+  const expectedTo = Math.max(anchor, head)
+  const from = validateBoundedInteger(owner, `${coordinate}.from`, record.from, {
+    minimum: expectedFrom,
+    maximum: expectedFrom,
+  })
+  const to = validateBoundedInteger(owner, `${coordinate}.to`, record.to, {
+    minimum: expectedTo,
+    maximum: expectedTo,
+  })
+  const empty = validateBoolean(owner, `${coordinate}.empty`, record.empty)
+  if (empty !== (anchor === head)) {
+    throw new TypeError(
+      `${owner}: ${coordinate}.empty не соответствует anchor/head. `
+      + `/ ${owner}: ${coordinate}.empty does not match anchor/head.`,
+    )
+  }
+  return Object.freeze({ anchor, head, from, to, empty })
+}
+
+/** Validates a serializable view-state snapshot against the current document. */
+export function validateCodeEditorViewState(
+  owner: string,
+  value: unknown,
+  documentLength: number,
+): SCodeEditorViewState {
+  const record = assertPlainExactRecord(owner, 'viewState', value, VIEW_STATE_KEYS)
+  return Object.freeze({
+    selection: validateCodeEditorSelectionRange(owner, 'viewState.selection', record.selection, documentLength),
+    scrollTop: validateNonNegativeFiniteNumber(owner, 'viewState.scrollTop', record.scrollTop),
+    scrollLeft: validateNonNegativeFiniteNumber(owner, 'viewState.scrollLeft', record.scrollLeft),
+  })
+}
+
+/** Runtime-validates controlled diagnostics and preserves their consumer-owned IDs. */
+export function validateCodeEditorDiagnostics(
+  owner: string,
+  value: unknown,
+  documentLength: number,
+): readonly SCodeEditorDiagnostic<SCodeEditorDiagnosticId>[] {
+  if (!Array.isArray(value)) {
+    throw new TypeError(`${owner}: diagnostics должен быть массивом. / ${owner}: diagnostics must be an array.`)
+  }
+  const ids = new Set<SCodeEditorDiagnosticId>()
+  value.forEach((candidate: unknown, index: number) => {
+    const coordinate = `diagnostics[${index}]`
+    const record = assertPlainExactRecord(owner, coordinate, candidate, DIAGNOSTIC_KEYS)
+    const id = validateDiagnosticId(owner, `${coordinate}.id`, record.id)
+    if (ids.has(id)) {
+      throw new TypeError(
+        `${owner}: ${coordinate}.id дублирует ${JSON.stringify(id)}. `
+        + `/ ${owner}: ${coordinate}.id duplicates ${JSON.stringify(id)}.`,
+      )
+    }
+    ids.add(id)
+    validateExactString(owner, `${coordinate}.severity`, record.severity, S_CODE_EDITOR_DIAGNOSTIC_SEVERITIES)
+    validateNonEmptyString(owner, `${coordinate}.message`, record.message)
+    validateCodeEditorRange(owner, coordinate, { from: record.from, to: record.to }, documentLength)
+    if (record.source !== undefined) validateNonEmptyString(owner, `${coordinate}.source`, record.source)
+    if (record.code !== undefined) validateDiagnosticId(owner, `${coordinate}.code`, record.code)
+  })
+  return value as readonly SCodeEditorDiagnostic<SCodeEditorDiagnosticId>[]
+}

package/src/components/shared/data-display/codeWorkspace.ts

@@ -0,0 +1,233 @@
+import {
+  validateBoolean,
+  validateNonEmptyString,
+} from '../../../internal/runtimeContract'
+import {
+  validateCodeEditorCapabilities,
+  validateCodeEditorLanguage,
+  validateCodeEditorVariant,
+  type CodeEditorCapabilitiesContract,
+  type CodeEditorLanguageContract,
+} from '../../../internal/codeEditorContract'
+import {
+  validateCodeEditorDiagnostics,
+  type SCodeEditorDiagnostic,
+  type SCodeEditorDiagnosticId,
+  type SCodeEditorRange,
+  type SCodeEditorSelectionRange,
+  type SCodeEditorSelectionSnapshot,
+  type SCodeEditorViewState,
+} from './codeEditor'
+
+export type SCodeWorkspaceDocumentKey = string
+export type SCodeWorkspaceSessionKey = string
+export type SCodeWorkspaceRevision = string | number
+
+/** Controlled document descriptor. Revision changes replace only this editor session and reset its local history. */
+export interface SCodeWorkspaceDocument {
+  readonly key: SCodeWorkspaceDocumentKey
+  readonly sessionKey: SCodeWorkspaceSessionKey
+  readonly label: string
+  readonly value: string
+  readonly revision: SCodeWorkspaceRevision
+  readonly language: CodeEditorLanguageContract
+  readonly capabilities: CodeEditorCapabilitiesContract
+  readonly diagnostics?: readonly SCodeEditorDiagnostic<SCodeEditorDiagnosticId>[]
+  readonly readOnly?: boolean
+  readonly disabled?: boolean
+  readonly invalid?: boolean
+  readonly closable?: boolean
+  readonly placeholder?: string
+  readonly variant?: 'code' | 'sql'
+}
+
+/** Controlled text change. Revision stays unchanged until the consumer supplies an authoritative replacement. */
+export interface SCodeWorkspaceDocumentChange {
+  readonly key: SCodeWorkspaceDocumentKey
+  readonly sessionKey: SCodeWorkspaceSessionKey
+  readonly revision: SCodeWorkspaceRevision
+  readonly value: string
+}
+
+export interface SCodeWorkspaceSelectionChange {
+  readonly key: SCodeWorkspaceDocumentKey
+  readonly sessionKey: SCodeWorkspaceSessionKey
+  readonly selection: SCodeEditorSelectionRange
+}
+
+export interface SCodeWorkspaceViewStateChange {
+  readonly key: SCodeWorkspaceDocumentKey
+  readonly sessionKey: SCodeWorkspaceSessionKey
+  readonly viewState: SCodeEditorViewState
+}
+
+export interface SCodeWorkspaceReleaseRequest {
+  readonly key: SCodeWorkspaceDocumentKey
+  readonly sessionKey: SCodeWorkspaceSessionKey
+}
+
+export interface SCodeWorkspaceDocumentState {
+  readonly key: SCodeWorkspaceDocumentKey
+  readonly sessionKey: SCodeWorkspaceSessionKey
+  readonly revision: SCodeWorkspaceRevision
+  readonly selection: SCodeEditorSelectionSnapshot
+  readonly viewState: SCodeEditorViewState
+}
+
+export interface SCodeWorkspaceEditorApi {
+  focusActive(): void
+  revealRange(key: SCodeWorkspaceDocumentKey, range: SCodeEditorRange): void
+  captureDocumentState(key: SCodeWorkspaceDocumentKey): SCodeWorkspaceDocumentState
+  releaseSession(sessionKey: SCodeWorkspaceSessionKey): void
+}
+
+const DOCUMENT_KEYS = new Set([
+  'key',
+  'sessionKey',
+  'label',
+  'value',
+  'revision',
+  'language',
+  'capabilities',
+  'diagnostics',
+  'readOnly',
+  'disabled',
+  'invalid',
+  'closable',
+  'placeholder',
+  'variant',
+])
+
+function assertPlainExactRecord(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+  allowed: ReadonlySet<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.has(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
+}
+
+function validateStableKey(owner: string, coordinate: string, value: unknown): string {
+  const result = validateNonEmptyString(owner, coordinate, value)
+  if (result !== result.trim()) {
+    throw new TypeError(
+      `${owner}: ${coordinate} не должен содержать окружающие пробелы. `
+      + `/ ${owner}: ${coordinate} must not contain surrounding whitespace.`,
+    )
+  }
+  return result
+}
+
+function validateRevision(owner: string, coordinate: string, value: unknown): SCodeWorkspaceRevision {
+  if (typeof value === 'string') return validateStableKey(owner, coordinate, value)
+  if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) return value
+  throw new TypeError(
+    `${owner}: ${coordinate} должен быть непустой строкой или неотрицательным safe integer. `
+    + `/ ${owner}: ${coordinate} must be a non-empty string or non-negative safe integer.`,
+  )
+}
+
+function validateOptionalBoolean(owner: string, coordinate: string, value: unknown, fallback: boolean): boolean {
+  return value === undefined ? fallback : validateBoolean(owner, coordinate, value)
+}
+
+function validateOptionalString(owner: string, coordinate: string, value: unknown): string | undefined {
+  return value === undefined ? undefined : validateNonEmptyString(owner, coordinate, value)
+}
+
+/** Validates and freezes the exact controlled document contract without normalizing invalid input. */
+export function validateCodeWorkspaceDocument(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+): SCodeWorkspaceDocument {
+  const record = assertPlainExactRecord(owner, coordinate, value, DOCUMENT_KEYS)
+  if (typeof record.value !== 'string') {
+    throw new TypeError(`${owner}: ${coordinate}.value должен быть строкой. / ${owner}: ${coordinate}.value must be a string.`)
+  }
+  const diagnostics = validateCodeEditorDiagnostics(
+    owner,
+    record.diagnostics ?? [],
+    record.value.length,
+  )
+  const placeholder = validateOptionalString(owner, `${coordinate}.placeholder`, record.placeholder)
+  const variant = record.variant === undefined
+    ? 'code'
+    : validateCodeEditorVariant(owner, record.variant)
+  return Object.freeze({
+    key: validateStableKey(owner, `${coordinate}.key`, record.key),
+    sessionKey: validateStableKey(owner, `${coordinate}.sessionKey`, record.sessionKey),
+    label: validateNonEmptyString(owner, `${coordinate}.label`, record.label),
+    value: record.value,
+    revision: validateRevision(owner, `${coordinate}.revision`, record.revision),
+    language: validateCodeEditorLanguage(owner, record.language),
+    capabilities: validateCodeEditorCapabilities(owner, record.capabilities),
+    diagnostics,
+    readOnly: validateOptionalBoolean(owner, `${coordinate}.readOnly`, record.readOnly, false),
+    disabled: validateOptionalBoolean(owner, `${coordinate}.disabled`, record.disabled, false),
+    invalid: validateOptionalBoolean(owner, `${coordinate}.invalid`, record.invalid, false),
+    closable: validateOptionalBoolean(owner, `${coordinate}.closable`, record.closable, true),
+    ...(placeholder === undefined ? {} : { placeholder }),
+    variant,
+  })
+}
+
+/** Validates document/session uniqueness for one workspace inventory. */
+export function validateCodeWorkspaceDocuments(
+  owner: string,
+  value: unknown,
+): readonly SCodeWorkspaceDocument[] {
+  if (!Array.isArray(value)) {
+    throw new TypeError(`${owner}: documents должен быть массивом. / ${owner}: documents must be an array.`)
+  }
+  const keys = new Set<string>()
+  const sessionKeys = new Set<string>()
+  const documents = value.map((document, index) => {
+    const validated = validateCodeWorkspaceDocument(owner, `documents[${index}]`, document)
+    if (keys.has(validated.key)) {
+      throw new RangeError(`${owner}: duplicate document key ${JSON.stringify(validated.key)}.`)
+    }
+    if (sessionKeys.has(validated.sessionKey)) {
+      throw new RangeError(`${owner}: duplicate sessionKey ${JSON.stringify(validated.sessionKey)}.`)
+    }
+    keys.add(validated.key)
+    sessionKeys.add(validated.sessionKey)
+    return validated
+  })
+  return Object.freeze(documents)
+}
+
+/** Validates controlled selection and rejects missing active documents. */
+export function validateCodeWorkspaceActiveKey(
+  owner: string,
+  value: unknown,
+  documents: readonly SCodeWorkspaceDocument[],
+): SCodeWorkspaceDocumentKey | null {
+  if (documents.length === 0) {
+    if (value === null) return null
+    throw new RangeError(`${owner}: activeKey должен быть null для пустого workspace. / ${owner}: activeKey must be null for an empty workspace.`)
+  }
+  const key = validateStableKey(owner, 'activeKey', value)
+  if (!documents.some((document) => document.key === key)) {
+    throw new RangeError(`${owner}: activeKey ${JSON.stringify(key)} отсутствует в documents. / ${owner}: activeKey ${JSON.stringify(key)} is absent from documents.`)
+  }
+  return key
+}