@pgcorp/ui-kit 0.1.0

package/src/components/shared/graph/_internal/graphViewportContract.ts

@@ -0,0 +1,362 @@
+/** Поддерживаемые семантические тона графа. / Supported semantic graph tones. */
+export const S_GRAPH_TONES = [
+  'neutral',
+  'primary',
+  'info',
+  'success',
+  'warning',
+  'danger',
+  'accent',
+] as const
+
+/** Семантический тон, разрешаемый UI-kit в theme tokens. / Theme-token-resolved semantic tone. */
+export type SGraphTone = (typeof S_GRAPH_TONES)[number]
+
+/** Семантическая роль узла в раскладке. / Semantic node role in the layout. */
+export type SGraphNodeRole = 'item' | 'group' | 'coverage' | 'relation'
+
+/** Точная позиция узла в координатах графа. / Exact position in graph coordinates. */
+export interface SGraphPosition {
+  x: number
+  y: number
+}
+
+/** Публичные данные узла без presentation colors. / Public node data without presentation colors. */
+export interface SGraphNode {
+  id: string
+  label: string
+  role: SGraphNodeRole
+  kind: string
+  group?: string | null
+  tone: SGraphTone
+  size: number
+  x: number
+  y: number
+  count?: number | null
+  forceLabel?: boolean
+  dragGroupIds?: readonly string[]
+  payload?: Record<string, unknown> | null
+}
+
+/** Публичные данные ребра без presentation colors. / Public edge data without presentation colors. */
+export interface SGraphEdge {
+  id: string
+  source: string
+  target: string
+  relationType: string
+  tone: SGraphTone
+  size?: number
+  opacity?: number
+  hidden?: boolean
+  showOnInteractionOnly?: boolean
+  payload?: Record<string, unknown> | null
+}
+
+/** Полный immutable input графа. / Complete immutable graph input. */
+export interface SGraphViewportGraph {
+  nodes: readonly SGraphNode[]
+  edges: readonly SGraphEdge[]
+}
+
+/** Controlled отсутствие или один выбранный узел. / Controlled none-or-single node selection. */
+export type SGraphSelection =
+  | { mode: 'none' }
+  | { mode: 'single'; nodeId: string }
+
+/** Readonly или editable позиционирование с точным keyboard step. / Readonly or editable positioning with an exact keyboard step. */
+export type SGraphPositioning =
+  | { mode: 'readonly' }
+  | { mode: 'editable'; keyboardStep: number }
+
+/** Единый controlled interaction-контракт viewport. / Unified controlled viewport interaction contract. */
+export interface SGraphViewportInteraction {
+  selection: SGraphSelection
+  positioning: SGraphPositioning
+}
+
+/** Ошибка точного runtime-контракта графа. / Exact graph runtime contract error. */
+export class SGraphContractError extends TypeError {
+  override readonly name = 'SGraphContractError'
+}
+
+const graphNodeRoles = new Set<SGraphNodeRole>(['item', 'group', 'coverage', 'relation'])
+const graphTones = new Set<SGraphTone>(S_GRAPH_TONES)
+
+function graphContractError(path: string, message: string): SGraphContractError {
+  return new SGraphContractError(`SGraphViewport: ${path} ${message}`)
+}
+
+function assertRecord(value: unknown, path: string): asserts value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw graphContractError(path, 'должен быть object.')
+  }
+}
+
+function assertExactKeys(value: Record<string, unknown>, allowed: readonly string[], path: string): void {
+  const unexpected = Object.keys(value).filter((key) => !allowed.includes(key))
+  if (unexpected.length > 0) {
+    throw graphContractError(path, `содержит неизвестные поля: ${unexpected.join(', ')}.`)
+  }
+}
+
+function assertNonEmptyString(value: unknown, path: string): asserts value is string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw graphContractError(path, 'должен быть непустой строкой.')
+  }
+}
+
+function assertFiniteNumber(value: unknown, path: string): asserts value is number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw graphContractError(path, 'должен быть конечным числом.')
+  }
+}
+
+function assertTone(value: unknown, path: string): asserts value is SGraphTone {
+  if (!graphTones.has(value as SGraphTone)) {
+    throw graphContractError(path, `имеет неизвестное значение "${String(value)}".`)
+  }
+}
+
+const nodeKeys = [
+  'id',
+  'label',
+  'role',
+  'kind',
+  'group',
+  'tone',
+  'size',
+  'x',
+  'y',
+  'count',
+  'forceLabel',
+  'dragGroupIds',
+  'payload',
+] as const
+
+const edgeKeys = [
+  'id',
+  'source',
+  'target',
+  'relationType',
+  'tone',
+  'size',
+  'opacity',
+  'hidden',
+  'showOnInteractionOnly',
+  'payload',
+] as const
+
+function assertGraphNode(value: unknown, index: number): asserts value is SGraphNode {
+  const path = `graph.nodes[${index}]`
+  assertRecord(value, path)
+  assertExactKeys(value, nodeKeys, path)
+  assertNonEmptyString(value.id, `${path}.id`)
+  assertNonEmptyString(value.label, `${path}.label`)
+  if (!graphNodeRoles.has(value.role as SGraphNodeRole)) {
+    throw graphContractError(`${path}.role`, `имеет неизвестное значение "${String(value.role)}".`)
+  }
+  assertNonEmptyString(value.kind, `${path}.kind`)
+  assertTone(value.tone, `${path}.tone`)
+  assertFiniteNumber(value.size, `${path}.size`)
+  if (value.size <= 0) throw graphContractError(`${path}.size`, 'должен быть больше 0.')
+  assertFiniteNumber(value.x, `${path}.x`)
+  assertFiniteNumber(value.y, `${path}.y`)
+  if (value.group !== undefined && value.group !== null) {
+    assertNonEmptyString(value.group, `${path}.group`)
+  }
+  if (value.count !== undefined && value.count !== null) {
+    assertFiniteNumber(value.count, `${path}.count`)
+    if (!Number.isInteger(value.count) || value.count < 0) {
+      throw graphContractError(`${path}.count`, 'должен быть неотрицательным целым числом.')
+    }
+  }
+  if (value.forceLabel !== undefined && typeof value.forceLabel !== 'boolean') {
+    throw graphContractError(`${path}.forceLabel`, 'должен быть boolean.')
+  }
+  if (value.dragGroupIds !== undefined && !Array.isArray(value.dragGroupIds)) {
+    throw graphContractError(`${path}.dragGroupIds`, 'должен быть массивом node id.')
+  }
+  if (value.payload !== undefined && value.payload !== null) {
+    assertRecord(value.payload, `${path}.payload`)
+  }
+}
+
+function assertGraphEdge(value: unknown, index: number): asserts value is SGraphEdge {
+  const path = `graph.edges[${index}]`
+  assertRecord(value, path)
+  assertExactKeys(value, edgeKeys, path)
+  assertNonEmptyString(value.id, `${path}.id`)
+  assertNonEmptyString(value.source, `${path}.source`)
+  assertNonEmptyString(value.target, `${path}.target`)
+  assertNonEmptyString(value.relationType, `${path}.relationType`)
+  assertTone(value.tone, `${path}.tone`)
+  if (value.size !== undefined) {
+    assertFiniteNumber(value.size, `${path}.size`)
+    if (value.size <= 0) throw graphContractError(`${path}.size`, 'должен быть больше 0.')
+  }
+  if (value.opacity !== undefined) {
+    assertFiniteNumber(value.opacity, `${path}.opacity`)
+    if (value.opacity < 0 || value.opacity > 1) {
+      throw graphContractError(`${path}.opacity`, 'должен находиться в диапазоне 0..1.')
+    }
+  }
+  for (const key of ['hidden', 'showOnInteractionOnly'] as const) {
+    if (value[key] !== undefined && typeof value[key] !== 'boolean') {
+      throw graphContractError(`${path}.${key}`, 'должен быть boolean.')
+    }
+  }
+  if (value.payload !== undefined && value.payload !== null) {
+    assertRecord(value.payload, `${path}.payload`)
+  }
+}
+
+/**
+ * Проверяет точный граф до передачи в Graphology/Sigma без silent skip, clamp или merge.
+ * Validates the exact graph before Graphology/Sigma without silent skips, clamps, or merges.
+ */
+export function assertSGraphViewportGraph(value: unknown): asserts value is SGraphViewportGraph {
+  assertRecord(value, 'graph')
+  assertExactKeys(value, ['nodes', 'edges'], 'graph')
+  if (!Array.isArray(value.nodes)) throw graphContractError('graph.nodes', 'должен быть массивом.')
+  if (!Array.isArray(value.edges)) throw graphContractError('graph.edges', 'должен быть массивом.')
+
+  const nodeIds = new Set<string>()
+  value.nodes.forEach((node, index) => {
+    assertGraphNode(node, index)
+    if (nodeIds.has(node.id)) {
+      throw graphContractError(`graph.nodes[${index}].id`, `дублирует node id "${node.id}".`)
+    }
+    nodeIds.add(node.id)
+  })
+
+  value.nodes.forEach((node, nodeIndex) => {
+    if (!node.dragGroupIds) return
+    const groupIds = new Set<string>()
+    node.dragGroupIds.forEach((groupId: string, groupIndex: number) => {
+      assertNonEmptyString(groupId, `graph.nodes[${nodeIndex}].dragGroupIds[${groupIndex}]`)
+      if (groupId === node.id) {
+        throw graphContractError(`graph.nodes[${nodeIndex}].dragGroupIds[${groupIndex}]`, 'не может ссылаться на сам узел.')
+      }
+      if (!nodeIds.has(groupId)) {
+        throw graphContractError(
+          `graph.nodes[${nodeIndex}].dragGroupIds[${groupIndex}]`,
+          `ссылается на отсутствующий node "${groupId}".`,
+        )
+      }
+      if (groupIds.has(groupId)) {
+        throw graphContractError(
+          `graph.nodes[${nodeIndex}].dragGroupIds[${groupIndex}]`,
+          `дублирует node id "${groupId}".`,
+        )
+      }
+      groupIds.add(groupId)
+    })
+  })
+
+  const edgeIds = new Set<string>()
+  value.edges.forEach((edge, index) => {
+    assertGraphEdge(edge, index)
+    if (edgeIds.has(edge.id)) {
+      throw graphContractError(`graph.edges[${index}].id`, `дублирует edge id "${edge.id}".`)
+    }
+    edgeIds.add(edge.id)
+    if (!nodeIds.has(edge.source)) {
+      throw graphContractError(`graph.edges[${index}].source`, `ссылается на отсутствующий node "${edge.source}".`)
+    }
+    if (!nodeIds.has(edge.target)) {
+      throw graphContractError(`graph.edges[${index}].target`, `ссылается на отсутствующий node "${edge.target}".`)
+    }
+  })
+}
+
+/**
+ * Проверяет controlled selection и positioning как один exact interaction-контракт.
+ * Validates controlled selection and positioning as one exact interaction contract.
+ */
+export function assertSGraphViewportInteraction(
+  value: unknown,
+  graph: SGraphViewportGraph,
+): asserts value is SGraphViewportInteraction {
+  assertRecord(value, 'interaction')
+  assertExactKeys(value, ['selection', 'positioning'], 'interaction')
+
+  assertRecord(value.selection, 'interaction.selection')
+  if (value.selection.mode === 'none') {
+    assertExactKeys(value.selection, ['mode'], 'interaction.selection')
+  } else if (value.selection.mode === 'single') {
+    assertExactKeys(value.selection, ['mode', 'nodeId'], 'interaction.selection')
+    assertNonEmptyString(value.selection.nodeId, 'interaction.selection.nodeId')
+    const selectedNodeId = value.selection.nodeId
+    if (!graph.nodes.some((node) => node.id === selectedNodeId)) {
+      throw graphContractError(
+        'interaction.selection.nodeId',
+        `ссылается на отсутствующий node "${selectedNodeId}".`,
+      )
+    }
+  } else {
+    throw graphContractError(
+      'interaction.selection.mode',
+      `имеет неизвестное значение "${String(value.selection.mode)}".`,
+    )
+  }
+
+  assertRecord(value.positioning, 'interaction.positioning')
+  if (value.positioning.mode === 'readonly') {
+    assertExactKeys(value.positioning, ['mode'], 'interaction.positioning')
+  } else if (value.positioning.mode === 'editable') {
+    assertExactKeys(value.positioning, ['mode', 'keyboardStep'], 'interaction.positioning')
+    assertFiniteNumber(value.positioning.keyboardStep, 'interaction.positioning.keyboardStep')
+    if (value.positioning.keyboardStep <= 0) {
+      throw graphContractError('interaction.positioning.keyboardStep', 'должен быть больше 0.')
+    }
+  } else {
+    throw graphContractError(
+      'interaction.positioning.mode',
+      `имеет неизвестное значение "${String(value.positioning.mode)}".`,
+    )
+  }
+}
+
+/** Режим масштабирования размеров узлов Sigma. / Sigma node-size scaling mode. */
+export type SGraphNodeSizeMode = 'screen' | 'graph'
+
+/** Измеряемая фаза renderer lifecycle. / Measured renderer lifecycle phase. */
+export type SGraphRenderMetricPhase = 'sigma_mount' | 'graph_replace'
+
+/** Метрика завершённой renderer-фазы. / Completed renderer-phase metric. */
+export interface SGraphRenderMetric {
+  phase: SGraphRenderMetricPhase
+  durationMs: number
+  nodes: number
+  edges: number
+  renderer: 'sigma'
+}
+
+/** Машиночитаемая причина отказа renderer. / Machine-readable renderer failure reason. */
+export type SGraphRenderErrorReason = 'webgl_unavailable' | 'invalid_graph' | 'sigma_mount_failed'
+
+/** Диагностируемый отказ renderer с размером входа. / Diagnosable renderer failure with input size. */
+export interface SGraphRenderError {
+  reason: SGraphRenderErrorReason
+  message: string
+  nodes: number
+  edges: number
+}
+
+/** Координаты pointer относительно viewport. / Pointer coordinates relative to the viewport. */
+export interface SGraphNodePointer {
+  x: number
+  y: number
+}
+
+/** Hover-событие узла с pointer coordinates. / Node hover event with pointer coordinates. */
+export interface SGraphNodePointerEvent {
+  nodeId: string
+  pointer: SGraphNodePointer
+}
+
+/** Controlled изменение позиции одного узла. / Controlled position change for one node. */
+export interface SGraphPositionChange {
+  nodeId: string
+  position: SGraphPosition
+}

package/src/components/shared/markdown.ts

@@ -0,0 +1,169 @@
+import DOMPurify from 'dompurify'
+import { marked } from 'marked'
+
+/** Закрытый tag contract очищенного document content. / Closed tag contract for sanitized document content. */
+export const SANITIZED_DOCUMENT_TAGS = [
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'p',
+    'br',
+    'hr',
+    'strong',
+    'em',
+    'b',
+    'i',
+    'u',
+    's',
+    'span',
+    'ul',
+    'ol',
+    'li',
+    'blockquote',
+    'code',
+    'pre',
+    'a',
+    'img',
+    'table',
+    'thead',
+    'tbody',
+    'tr',
+    'th',
+    'td',
+    'div',
+    'section',
+    'article',
+    'header',
+    'footer',
+    'sup',
+    'sub',
+    'small',
+    'mark',
+    'del',
+    'ins',
+] as const
+
+/** Закрытый attribute contract очищенного document content. / Closed attribute contract for sanitized document content. */
+export const SANITIZED_DOCUMENT_ATTRIBUTES = [
+    'href',
+    'title',
+    'src',
+    'alt',
+    'class',
+    'id',
+    'colspan',
+    'rowspan',
+] as const
+
+/** Атрибуты, доступные typed renderer после presentation mapping. / Attributes available to the typed renderer after presentation mapping. */
+export const SANITIZED_DOCUMENT_RENDER_ATTRIBUTES = [
+  ...SANITIZED_DOCUMENT_ATTRIBUTES.filter((attribute) => attribute !== 'id'),
+  'data-s-doc-anchor',
+  'data-s-doc-align',
+] as const
+
+const domPurifyConfig = {
+  ALLOWED_TAGS: [...SANITIZED_DOCUMENT_TAGS],
+  ALLOWED_ATTR: [...SANITIZED_DOCUMENT_ATTRIBUTES],
+  FORBID_TAGS: [
+    'script',
+    'style',
+    'link',
+    'meta',
+    'iframe',
+    'object',
+    'embed',
+    'form',
+    'input',
+    'button',
+    'select',
+    'textarea',
+  ],
+  FORBID_ATTR: [
+    'style',
+    'width',
+    'height',
+    'target',
+    'rel',
+    'onerror',
+    'onload',
+    'onclick',
+    'onmouseover',
+    'onmouseout',
+    'onfocus',
+    'onblur',
+    'onchange',
+    'onsubmit',
+  ],
+  ALLOW_DATA_ATTR: false,
+  USE_PROFILES: { html: true },
+}
+
+const generatedCodeClass = /^(?:hljs|hljs-[a-z0-9_-]+|language-[a-z0-9-]+)$/
+
+function mapSanitizedDocumentPresentation(html: string): string {
+  const template = document.createElement('template')
+  template.innerHTML = html
+
+  for (const cell of template.content.querySelectorAll<HTMLTableCellElement>('th[align], td[align]')) {
+    const alignment = cell.getAttribute('align')?.trim().toLowerCase()
+    cell.removeAttribute('align')
+    if (alignment === 'left' || alignment === 'center' || alignment === 'right') {
+      cell.dataset.sDocAlign = alignment
+    }
+  }
+
+  for (const element of template.content.querySelectorAll<HTMLElement>('[align]')) {
+    element.removeAttribute('align')
+  }
+
+  for (const element of template.content.querySelectorAll<HTMLElement>('[id]')) {
+    const anchor = element.getAttribute('id')?.trim()
+    element.removeAttribute('id')
+    if (anchor) element.dataset.sDocAnchor = anchor
+  }
+
+  for (const element of template.content.querySelectorAll<HTMLElement>('[class]')) {
+    const allowsGeneratedClass = element.matches('code, code span')
+    const classes = allowsGeneratedClass
+      ? [...element.classList].filter((className) => generatedCodeClass.test(className))
+      : []
+    if (classes.length === 0) element.removeAttribute('class')
+    else element.className = classes.join(' ')
+  }
+
+  for (const anchor of template.content.querySelectorAll<HTMLAnchorElement>('a:not([href])')) {
+    anchor.replaceWith(...anchor.childNodes)
+  }
+
+  return template.innerHTML
+}
+
+/**
+ * Очищает document HTML и отображает разрешённые presentation hints в закрытый контракт.
+ * Sanitizes document HTML and maps allowed presentation hints into a closed contract.
+ */
+export function sanitizeDocumentHtml(content: string): string {
+  if (typeof content !== 'string') {
+    throw new TypeError('sanitizeDocumentHtml: content must be a string')
+  }
+  return mapSanitizedDocumentPresentation(DOMPurify.sanitize(content, domPurifyConfig))
+}
+
+export function renderMarkdownToSafeHtml(content: string): string {
+  if (typeof content !== 'string') {
+    throw new TypeError(
+      'renderMarkdownToSafeHtml: content должен быть строкой. '
+      + '/ renderMarkdownToSafeHtml: content must be a string',
+    )
+  }
+  const rendered = marked.parse(content, {
+    gfm: true,
+    breaks: true,
+  }) as string
+
+  return sanitizeDocumentHtml(rendered)
+}