@pgcorp/ui-kit 0.8.1 → 0.10.0

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
+}