@pgcorp/ui-kit 0.1.0

package/src/components/shared/_internal/treeRuntime.ts

@@ -0,0 +1,203 @@
+import { inject, onBeforeUnmount, onMounted } from 'vue'
+import type { ComputedRef, InjectionKey, Ref } from 'vue'
+import type {
+  STreeNodeContentScope,
+  TreeActionsLayout,
+  TreeActivationOrigin,
+  TreeDensity,
+  TreeExpandControl,
+  SelectionKey,
+  TreeModel,
+  TreeRowVariant,
+  TreeSelection,
+  TreeSelectionRail,
+} from '../complex/types'
+
+export const TREE_RUNTIME_KEY = 's-tree-runtime'
+export const TREE_ACTION_CONTEXT_KEY: InjectionKey<TreeActionContext> = Symbol('s-tree-action-context')
+
+export interface RegisteredTreeItem<T extends object, K extends SelectionKey> {
+  key: K
+  parentKey?: K
+  node: T
+  element: HTMLElement
+  activate(origin: TreeActivationOrigin): void
+  select(): void
+  toggle(): void
+  expanded(): boolean
+  hasChildren(): boolean
+  disabled(): boolean
+}
+
+export type TreeActionKey = symbol
+
+export interface RegisteredTreeAction {
+  readonly key: TreeActionKey
+  readonly element: HTMLElement
+  focus(options?: FocusOptions): void
+  disabled(): boolean
+}
+
+export interface TreeActionContext {
+  register(action: RegisteredTreeAction): void
+  unregister(action: RegisteredTreeAction): void
+}
+
+function compareRegisteredElements(
+  owner: string,
+  left: { readonly element: HTMLElement },
+  right: { readonly element: HTMLElement },
+): number {
+  if (left.element === right.element) return 0
+  const position = left.element.compareDocumentPosition(right.element)
+  const nodeConstructor = left.element.ownerDocument.defaultView?.Node
+  if (!nodeConstructor) {
+    throw new Error(`${owner}: registered elements require an active DOM document`)
+  }
+  if ((position & nodeConstructor.DOCUMENT_POSITION_DISCONNECTED) !== 0) {
+    throw new Error(`${owner}: registered elements must belong to the same DOM tree`)
+  }
+  if ((position & nodeConstructor.DOCUMENT_POSITION_FOLLOWING) !== 0) return -1
+  if ((position & nodeConstructor.DOCUMENT_POSITION_PRECEDING) !== 0) return 1
+  throw new Error(`${owner}: registered elements have no deterministic DOM order`)
+}
+
+function orderedRegistrations<R extends { readonly element: HTMLElement }>(
+  owner: string,
+  root: HTMLElement | null,
+  registrations: Iterable<R>,
+): R[] {
+  if (!root) return []
+  return [...registrations]
+    .filter((registration) => registration.element.isConnected && root.contains(registration.element))
+    .sort((left, right) => compareRegisteredElements(owner, left, right))
+}
+
+export class TreeItemRegistrationStore<T extends object, K extends SelectionKey> {
+  readonly #items = new Map<K, RegisteredTreeItem<T, K>>()
+  readonly #root: () => HTMLElement | null
+
+  constructor(root: () => HTMLElement | null) {
+    this.#root = root
+  }
+
+  register(item: RegisteredTreeItem<T, K>): void {
+    const current = this.#items.get(item.key)
+    if (current && current.element !== item.element) {
+      throw new Error(`STree: runtime registration collision for ${typeof item.key}:${String(item.key)}`)
+    }
+    this.#items.set(item.key, item)
+  }
+
+  unregister(key: K): void {
+    this.#items.delete(key)
+  }
+
+  get(key: K): RegisteredTreeItem<T, K> | undefined {
+    return this.#items.get(key)
+  }
+
+  ordered(): RegisteredTreeItem<T, K>[] {
+    return orderedRegistrations('STree item registry', this.#root(), this.#items.values())
+  }
+}
+
+export class TreeActionRegistrationStore implements TreeActionContext {
+  readonly #actions = new Map<TreeActionKey, RegisteredTreeAction>()
+  readonly #root: () => HTMLElement | null
+
+  constructor(root: () => HTMLElement | null) {
+    this.#root = root
+  }
+
+  register(action: RegisteredTreeAction): void {
+    const current = this.#actions.get(action.key)
+    if (current && current !== action) {
+      throw new Error(`STree: action registration collision for ${String(action.key)}`)
+    }
+    const elementOwner = [...this.#actions.values()].find((candidate) =>
+      candidate.key !== action.key && candidate.element === action.element,
+    )
+    if (elementOwner) {
+      throw new Error(
+        `STree: action element is already registered by ${String(elementOwner.key)}`,
+      )
+    }
+    this.#actions.set(action.key, action)
+  }
+
+  unregister(action: RegisteredTreeAction): void {
+    const current = this.#actions.get(action.key)
+    if (!current) return
+    if (current !== action) {
+      throw new Error(`STree: stale action unregistration for ${String(action.key)}`)
+    }
+    this.#actions.delete(action.key)
+  }
+
+  orderedEnabled(): RegisteredTreeAction[] {
+    return orderedRegistrations(
+      'STree action registry',
+      this.#root(),
+      this.#actions.values(),
+    ).filter((action) => !action.disabled())
+  }
+
+  actionForTarget(target: EventTarget | null): RegisteredTreeAction | undefined {
+    if (!(target instanceof Node)) return undefined
+    return this.orderedEnabled().find((action) =>
+      action.element === target || action.element.contains(target),
+    )
+  }
+}
+
+export function useTreeActionRegistration(options: Readonly<{
+  owner: string
+  element: Readonly<Ref<HTMLElement | null>>
+  disabled: () => boolean
+}>): boolean {
+  const context = inject(TREE_ACTION_CONTEXT_KEY, null)
+  if (!context) return false
+
+  const key = Symbol(options.owner)
+  let registration: RegisteredTreeAction | undefined
+  onMounted(() => {
+    const element = options.element.value
+    if (!element) {
+      throw new Error(`STree: ${options.owner} action registration requires a mounted element`)
+    }
+    registration = {
+      key,
+      element,
+      focus: (focusOptions) => element.focus(focusOptions),
+      disabled: options.disabled,
+    }
+    context.register(registration)
+  })
+  onBeforeUnmount(() => {
+    if (registration) context.unregister(registration)
+  })
+  return true
+}
+
+export interface TreeRuntime<T extends object, K extends SelectionKey> {
+  model: TreeModel<T, K>
+  selection: ComputedRef<TreeSelection<K>>
+  expanded: ComputedRef<ReadonlySet<K>>
+  density: ComputedRef<TreeDensity>
+  actionsLayout: ComputedRef<TreeActionsLayout>
+  expandControl: ComputedRef<TreeExpandControl>
+  selectionRail: ComputedRef<TreeSelectionRail>
+  rowVariant: ComputedRef<TreeRowVariant>
+  activeKey: Ref<K | undefined>
+  activateNode(node: T, origin: TreeActivationOrigin): void
+  selectNode(node: T): void
+  toggleNode(node: T): void
+  checkNode(node: T): void
+  multipleKeys(node: T): readonly K[]
+  register(item: RegisteredTreeItem<T, K>): void
+  unregister(key: K): void
+  handleItemKeydown(item: RegisteredTreeItem<T, K>, event: KeyboardEvent): void
+}
+
+export type TreeNodeScope<T extends object, K extends SelectionKey> = STreeNodeContentScope<T, K>

package/src/components/shared/_internal/useSelectionRoving.ts

@@ -0,0 +1,162 @@
+import { computed } from 'vue'
+import type { ComputedRef, Ref } from 'vue'
+
+/** Стабильный ключ, принимаемый владельцами выбора. / Stable key accepted by selection owners. */
+export type SelectionKey = string | number
+
+/** Ключ и точная координата его объявления для диагностики. / A key and its exact declaration coordinate for diagnostics. */
+export interface SelectionIdentity<T extends SelectionKey = SelectionKey> {
+  key: T
+  coordinate: string
+}
+
+/** Опция общего roving-focus с состоянием доступности. / A shared roving-focus option with availability state. */
+export interface SelectionRovingOption<T extends SelectionKey> {
+  value: T
+  disabled?: boolean
+}
+
+/** Публичный keyboard/focus-контракт владельца выбора. / Public keyboard/focus contract for a selection owner. */
+export interface SelectionRovingApi<T extends SelectionKey> {
+  focusableValue: ComputedRef<T | undefined>
+  register: (value: T, element: Element | null) => void
+  handleKeydown: (event: KeyboardEvent, value: T) => void
+}
+
+function invalidKeyMessage(component: string, coordinate: string): string {
+  return `${component}: ${coordinate} must be a non-empty string or a finite number`
+}
+
+/** Проверяет runtime-контракт identity в точной координате вызова. / Asserts the runtime identity contract at the exact caller coordinate. */
+export function assertSelectionKey(
+  component: string,
+  key: unknown,
+  coordinate: string,
+): asserts key is SelectionKey {
+  if (typeof key === 'string') {
+    if (key.trim().length === 0) throw new TypeError(invalidKeyMessage(component, coordinate))
+    return
+  }
+  if (typeof key === 'number' && Number.isFinite(key)) return
+  throw new TypeError(invalidKeyMessage(component, coordinate))
+}
+
+/** Возвращает type-aware token для DOM id, Vue key и lookup map. / Returns a type-aware token for DOM ids, Vue keys, and lookup maps. */
+export function selectionKeyToken(
+  component: string,
+  key: SelectionKey,
+  coordinate: string,
+): string {
+  assertSelectionKey(component, key, coordinate)
+  return typeof key === 'string'
+    ? `string:${encodeURIComponent(key)}`
+    : `number:${Object.is(key, -0) ? '0' : String(key)}`
+}
+
+/** Проверяет полный inventory identity и возвращает канонический индекс. / Validates a complete identity inventory and returns its canonical index. */
+export function validateSelectionIdentities<T extends SelectionKey>(
+  component: string,
+  identities: readonly SelectionIdentity<T>[],
+): ReadonlyMap<string, T> {
+  const keysByToken = new Map<string, T>()
+  const coordinatesByToken = new Map<string, string>()
+
+  for (const identity of identities) {
+    const token = selectionKeyToken(component, identity.key, identity.coordinate)
+    const previousCoordinate = coordinatesByToken.get(token)
+    if (previousCoordinate !== undefined) {
+      throw new Error(
+        `${component}: duplicate selection key at ${identity.coordinate}; first declared at ${previousCoordinate}`,
+      )
+    }
+    coordinatesByToken.set(token, identity.coordinate)
+    keysByToken.set(token, identity.key)
+  }
+
+  return keysByToken
+}
+
+function validateRovingOptions<T extends SelectionKey>(
+  component: string,
+  options: readonly SelectionRovingOption<T>[],
+): ReadonlyMap<string, T> {
+  return validateSelectionIdentities(component, options.map((option, index) => ({
+    key: option.value,
+    coordinate: `options[${index}].value`,
+  })))
+}
+
+function validateSelectedValue<T extends SelectionKey>(
+  component: string,
+  selectedValue: T | null | undefined,
+  optionsByToken: ReadonlyMap<string, T>,
+): void {
+  if (selectedValue === null || selectedValue === undefined) return
+  const token = selectionKeyToken(component, selectedValue, 'selectedValue')
+  if (!optionsByToken.has(token)) {
+    throw new Error(`${component}: selectedValue does not match any option`)
+  }
+}
+
+/**
+ * Управляет общим roving-focus без потери доменного типа ключа.
+ * Manages shared roving focus without losing the domain key type.
+ */
+export function useSelectionRoving<T extends SelectionKey>(config: {
+  options: ComputedRef<readonly SelectionRovingOption<T>[]>
+  selectedValue: Ref<T | null | undefined>
+  orientation?: 'horizontal' | 'vertical' | 'both'
+  select: (value: T) => void
+  component?: string
+}): SelectionRovingApi<T> {
+  const elements = new Map<T, HTMLElement>()
+  const orientation = config.orientation ?? 'both'
+  const component = config.component ?? 'useSelectionRoving'
+
+  const validatedOptions = computed(() => {
+    const options = config.options.value
+    const optionsByToken = validateRovingOptions(component, options)
+    validateSelectedValue(component, config.selectedValue.value, optionsByToken)
+    return options
+  })
+  const enabledOptions = computed(() => validatedOptions.value.filter((option) => !option.disabled))
+  const focusableValue = computed(() => {
+    const selectedValue = config.selectedValue.value
+    return enabledOptions.value.find((option) => option.value === selectedValue)?.value
+      ?? enabledOptions.value[0]?.value
+  })
+
+  const register = (value: T, element: Element | null): void => {
+    selectionKeyToken(component, value, 'registered value')
+    if (element instanceof HTMLElement) elements.set(value, element)
+    else elements.delete(value)
+  }
+
+  const handleKeydown = (event: KeyboardEvent, value: T): void => {
+    const direction = (
+      orientation !== 'vertical' && event.key === 'ArrowLeft' ? -1
+      : orientation !== 'vertical' && event.key === 'ArrowRight' ? 1
+      : orientation !== 'horizontal' && event.key === 'ArrowUp' ? -1
+      : orientation !== 'horizontal' && event.key === 'ArrowDown' ? 1
+      : null
+    )
+    const enabled = enabledOptions.value
+    if (enabled.length === 0) return
+
+    const currentIndex = enabled.findIndex((option) => option.value === value)
+    const target = event.key === 'Home'
+      ? enabled[0]
+      : event.key === 'End'
+        ? enabled[enabled.length - 1]
+        : direction === null
+          ? undefined
+          : enabled[(Math.max(currentIndex, 0) + direction + enabled.length) % enabled.length]
+    if (!target) return
+
+    event.preventDefault()
+    config.select(target.value)
+    elements.get(target.value)?.focus()
+  }
+
+  return { focusableValue, register, handleKeydown }
+}

package/src/components/shared/codeLanguages.ts

@@ -0,0 +1,168 @@
+import { StreamLanguage } from '@codemirror/language'
+import type { Extension } from '@codemirror/state'
+import { langNames, loadLanguage } from '@uiw/codemirror-extensions-langs'
+import { makefile } from 'codemirror-lang-makefile'
+import { dockerFile } from '@codemirror/legacy-modes/mode/dockerfile'
+import { nginx } from '@codemirror/legacy-modes/mode/nginx'
+import { shell } from '@codemirror/legacy-modes/mode/shell'
+import {
+  type CodeEditorLanguageContract,
+  validateCodeEditorLanguage,
+} from '../../internal/codeEditorContract'
+
+type NullableText = string | null | undefined
+
+const SPECIAL_FILENAMES: Record<string, string> = {
+  'cmakelists.txt': 'cmake',
+  'dockerfile': 'dockerfile',
+  'docker-compose.yml': 'yaml',
+  'docker-compose.yaml': 'yaml',
+  'compose.yml': 'yaml',
+  'compose.yaml': 'yaml',
+  '.env': 'properties',
+  '.env.example': 'properties',
+  '.env.local': 'properties',
+  '.env.development': 'properties',
+  '.env.production': 'properties',
+  'makefile': 'makefile',
+  'nginx.conf': 'nginx',
+}
+
+const LANGUAGE_ALIASES: Record<string, string> = {
+  bash: 'shell',
+  'c#': 'cs',
+  csharp: 'cs',
+  env: 'properties',
+  fish: 'shell',
+  handlebars: 'handlebars',
+  htm: 'html',
+  js: 'javascript',
+  jsonc: 'json',
+  json5: 'json',
+  log: 'text',
+  make: 'makefile',
+  md: 'markdown',
+  mk: 'makefile',
+  plaintext: 'text',
+  proto3: 'proto',
+  ps1: 'powershell',
+  psm1: 'powershell',
+  psd1: 'powershell',
+  py: 'python',
+  pyw: 'python',
+  pyi: 'python',
+  rbw: 'ruby',
+  sh: 'shell',
+  shellsession: 'shell',
+  ts: 'typescript',
+  text: 'text',
+  txt: 'text',
+  yaml: 'yaml',
+  yml: 'yaml',
+  zsh: 'shell',
+}
+
+const LEGACY_CODEMIRROR_LANGUAGES: Record<string, Extension> = {
+  dockerfile: StreamLanguage.define(dockerFile),
+  makefile: makefile(),
+  nginx: StreamLanguage.define(nginx),
+  shell: StreamLanguage.define(shell),
+}
+
+const CODEMIRROR_LANGUAGE_ALIASES: Record<string, string> = {
+  javascript: 'js',
+  powershell: 'ps1',
+  python: 'py',
+  ruby: 'rb',
+  rust: 'rs',
+  shell: 'bash',
+  typescript: 'ts',
+}
+
+const HIGHLIGHT_LANGUAGE_ALIASES: Record<string, string> = {
+  shell: 'bash',
+  text: 'plaintext',
+}
+
+type SupportedCodeMirrorLanguage = Parameters<typeof loadLanguage>[0]
+
+const SUPPORTED_CODEMIRROR_LANGUAGES = new Set<SupportedCodeMirrorLanguage>(langNames)
+
+function normalizeDetectedToken(value: NullableText): string | null {
+  if (!value) {
+    return null
+  }
+
+  const normalized = value.trim().toLowerCase().replace(/^\./, '')
+  if (!normalized) {
+    return null
+  }
+
+  return LANGUAGE_ALIASES[normalized] ?? normalized
+}
+
+function resolveLanguageFromFilePath(filePath: NullableText): string | null {
+  if (!filePath) {
+    return null
+  }
+
+  const normalizedPath = filePath.trim().toLowerCase()
+  if (!normalizedPath) {
+    return null
+  }
+
+  const basename = normalizedPath.split('/').pop() ?? normalizedPath
+  if (SPECIAL_FILENAMES[basename]) {
+    return SPECIAL_FILENAMES[basename]
+  }
+
+  if (basename.startsWith('dockerfile.')) {
+    return 'dockerfile'
+  }
+
+  if (!basename.includes('.')) {
+    return null
+  }
+
+  const extension = basename.split('.').pop()
+  return normalizeDetectedToken(extension)
+}
+
+function isSupportedCodeMirrorLanguage(value: string): value is SupportedCodeMirrorLanguage {
+  return SUPPORTED_CODEMIRROR_LANGUAGES.has(value as SupportedCodeMirrorLanguage)
+}
+
+export function resolveCodeLanguageKey(input: CodeEditorLanguageContract): string {
+  const language = validateCodeEditorLanguage('codeLanguages', input)
+  if (language.mode === 'explicit') {
+    return LANGUAGE_ALIASES[language.id] ?? language.id
+  }
+  const detected = resolveLanguageFromFilePath(language.filePath)
+  if (!detected) {
+    throw new RangeError(
+      `codeLanguages: невозможно определить язык по filePath ${JSON.stringify(language.filePath)}. `
+      + `/ codeLanguages: cannot detect a language from filePath ${JSON.stringify(language.filePath)}.`,
+    )
+  }
+  return detected
+}
+
+export function getCodeMirrorLanguageExtension(input: CodeEditorLanguageContract): Extension | null {
+  const languageKey = resolveCodeLanguageKey(input)
+
+  const codeMirrorLanguageKey = CODEMIRROR_LANGUAGE_ALIASES[languageKey] ?? languageKey
+
+  if (isSupportedCodeMirrorLanguage(codeMirrorLanguageKey)) {
+    const loadedLanguage = loadLanguage(codeMirrorLanguageKey)
+    if (loadedLanguage) {
+      return loadedLanguage
+    }
+  }
+
+  return LEGACY_CODEMIRROR_LANGUAGES[codeMirrorLanguageKey] ?? LEGACY_CODEMIRROR_LANGUAGES[languageKey] ?? null
+}
+
+export function resolveHighlightLanguageKey(input: CodeEditorLanguageContract): string {
+  const languageKey = resolveCodeLanguageKey(input)
+  return HIGHLIGHT_LANGUAGE_ALIASES[languageKey] ?? languageKey
+}

package/src/components/shared/complex/SKanbanCard.css

@@ -0,0 +1,8 @@
+@reference "../../../styles/reference.css";
+
+.s-kanban-card__content { @apply flex w-full min-w-0 flex-col; }
+.s-kanban-card__copy { @apply min-w-0; }
+.s-kanban-card__title { @apply block truncate text-sm font-medium text-surface-800 dark:text-surface-100; }
+.s-kanban-card__subtitle { @apply mt-0.5 block truncate text-xs text-surface-500 dark:text-surface-400; }
+.s-kanban-card__body { @apply mt-2 min-w-0; }
+.s-kanban-card__meta { @apply mt-2 flex min-w-0 flex-wrap items-center gap-2 text-xs text-surface-500 dark:text-surface-400; }

package/src/components/shared/complex/SKanbanCard.vue

@@ -0,0 +1,76 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type {
+  InteractiveSurfaceContract,
+  InteractiveSurfaceDensity,
+  InteractiveSurfacePadding,
+  InteractiveSurfaceRadius,
+  InteractiveSurfaceTone,
+} from '../controls/SInteractiveSurface.vue'
+import SActionCard from '../data-display/SActionCard.vue'
+import { useOwnedAttrs } from '../../../internal/ownedAttrs'
+
+defineOptions({ inheritAttrs: false })
+
+export interface Props {
+  title: string
+  subtitle?: string
+  surface?: InteractiveSurfaceContract
+  selected?: boolean
+  tone?: InteractiveSurfaceTone
+  density?: InteractiveSurfaceDensity
+  padding?: InteractiveSurfacePadding
+  radius?: InteractiveSurfaceRadius
+  fill?: boolean
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  subtitle: undefined,
+  surface: undefined,
+  selected: false,
+  tone: 'default',
+  density: 'comfortable',
+  padding: 'sm',
+  radius: 'md',
+  fill: false,
+})
+
+const emit = defineEmits<{
+  activate: [event: MouseEvent]
+}>()
+
+const resolvedSurface = computed<InteractiveSurfaceContract>(() => props.surface ?? { mode: 'static' })
+const ownedAttrs = useOwnedAttrs({ component: 'SKanbanCard', owner: 'canonical action-card surface' })
+
+function activate(event: MouseEvent): void {
+  emit('activate', event)
+}
+</script>
+
+<template>
+  <SActionCard
+    data-testid="s-kanban-card"
+    v-bind="ownedAttrs.bindings()"
+    :surface="resolvedSurface"
+    :selected="selected"
+    :tone="tone"
+    :density="density"
+    :padding="padding"
+    :radius="radius"
+    :fill="fill ? 'container' : 'content'"
+    @activate="activate"
+  >
+    <div class="s-kanban-card__content">
+      <span class="s-kanban-card__copy">
+        <span class="s-kanban-card__title">{{ title }}</span>
+        <span v-if="subtitle" class="s-kanban-card__subtitle">{{ subtitle }}</span>
+      </span>
+
+      <span v-if="$slots.default" class="s-kanban-card__body"><slot /></span>
+      <span v-if="$slots.meta" class="s-kanban-card__meta"><slot name="meta" /></span>
+    </div>
+    <template v-if="$slots.actions" #actions><slot name="actions" /></template>
+  </SActionCard>
+</template>
+
+<style lang="postcss" src="./SKanbanCard.css" scoped></style>