@pgcorp/ui-kit 0.1.0

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

@@ -0,0 +1,82 @@
+<template>
+  <SCollapsiblePanel
+    v-bind="ownedAttrs.bindings()"
+    :summary="validatedTitle"
+    summary-typography="strong"
+    :summary-badges="[{ id: 'item-count', label: validatedCount, severity: 'secondary' }]"
+    :open="open"
+    :default-open="defaultOpen"
+    :density="density"
+    header-variant="minimal"
+    surface="plain"
+    @update:open="$emit('update:open', $event)"
+    data-testid="s-kanban-lane"
+  >
+    <SStack v-if="validatedCount > 0" gap="control">
+      <slot />
+    </SStack>
+    <SEmptyState
+      v-else
+      :title="validatedEmptyText"
+      size="sm"
+    />
+  </SCollapsiblePanel>
+</template>
+
+<script setup lang="ts">
+import { computed, type VNodeChild } from 'vue'
+import { useOwnedAttrs } from '../../../internal/ownedAttrs'
+import { validateBoundedInteger, validateNonEmptyString } from '../../../internal/runtimeContract'
+import SStack from '../../layout/SStack.vue'
+import SCollapsiblePanel from '../containers/SCollapsiblePanel.vue'
+import SEmptyState from '../data-display/SEmptyState.vue'
+
+defineOptions({ inheritAttrs: false })
+
+/** Каноническая вертикальная lane-композиция поверх disclosure, stack и empty-state owners. / Canonical vertical lane composition over disclosure, stack, and empty-state owners. */
+export interface Props {
+  /** Пользовательская метка lane. / User-facing lane label. */
+  title: string
+  /** Точное число элементов в lane. / Exact number of items in the lane. */
+  count: number
+  /** Сообщение пустого состояния. / Empty-state message. */
+  emptyText?: string
+  /** Начальное состояние uncontrolled disclosure. / Initial uncontrolled disclosure state. */
+  defaultOpen?: boolean
+  /** Controlled disclosure state. / Controlled disclosure state. */
+  open?: boolean
+  /** Семантическая плотность disclosure. / Semantic disclosure density. */
+  density?: 'comfortable' | 'compact' | 'dense'
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  emptyText: 'Нет элементов',
+  defaultOpen: true,
+  open: undefined,
+  density: 'compact',
+})
+
+defineEmits<{
+  (e: 'update:open', value: boolean): void
+}>()
+
+defineSlots<{
+  /** Элементы lane; их presentation принадлежит переданным UI-kit owners. / Lane items whose presentation belongs to supplied UI-kit owners. */
+  default?: () => VNodeChild
+}>()
+
+const validatedTitle = computed(() => validateNonEmptyString('SKanbanLane', 'title', props.title))
+const validatedCount = computed(() => validateBoundedInteger(
+  'SKanbanLane',
+  'count',
+  props.count,
+  { minimum: 0, maximum: Number.MAX_SAFE_INTEGER },
+))
+const validatedEmptyText = computed(() => validateNonEmptyString(
+  'SKanbanLane',
+  'emptyText',
+  props.emptyText,
+))
+
+const ownedAttrs = useOwnedAttrs({ component: 'SKanbanLane', owner: 'collapsible lane composition' })
+</script>

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

@@ -0,0 +1,24 @@
+@reference "../../../styles/reference.css";
+
+.s-tree {
+  @apply h-full w-full text-sm;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+
+  --s-tree-branch-color: color-mix(in srgb, var(--color-surface-300) 68%, transparent);
+  --s-tree-branch-active-color: color-mix(in srgb, var(--color-primary-500) 34%, var(--color-surface-300));
+  --s-tree-row-border-bottom: 0 solid transparent;
+  --s-tree-row-background: transparent;
+  --s-tree-row-selected-bg: linear-gradient(
+    90deg,
+    color-mix(in srgb, var(--color-success-50) 82%, transparent),
+    color-mix(in srgb, var(--color-success-50) 28%, transparent) 72%,
+    transparent
+  );
+}
+
+.s-tree--row-table {
+  --s-tree-row-border-bottom: 1px solid color-mix(in srgb, var(--color-surface-200) 74%, transparent);
+  --s-tree-row-background: var(--color-surface-0);
+}

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

@@ -0,0 +1,288 @@
+<template>
+  <ul
+    v-bind="ownedAttrs.bindings()"
+    ref="treeRef"
+    class="s-tree"
+    role="tree"
+    :aria-label="props.label"
+    :aria-multiselectable="props.selection.mode === 'multiple' ? true : undefined"
+    :class="[
+      `s-tree--density-${props.density}`,
+      `s-tree--actions-${props.actionsLayout}`,
+      `s-tree--expand-${props.expandControl}`,
+      `s-tree--selection-rail-${props.selectionRail}`,
+      `s-tree--row-${props.rowVariant}`,
+    ]"
+  >
+    <!-- @vue-generic {T, K} -->
+    <STreeNode
+      v-for="(node, index) in validatedNodes"
+      :key="props.model.key(node)"
+      :node="node"
+      :level="0"
+      :position="index + 1"
+      :set-size="validatedNodes.length"
+    >
+      <template v-if="$slots['col-left']" #col-left="scope"><slot name="col-left" v-bind="scope" /></template>
+      <template v-if="$slots['col-center']" #col-center="scope"><slot name="col-center" v-bind="scope" /></template>
+      <template v-if="$slots.meta" #meta="scope"><slot name="meta" v-bind="scope" /></template>
+      <template v-if="$slots['persistent-actions']" #persistent-actions="scope"><slot name="persistent-actions" v-bind="scope" /></template>
+      <template v-if="$slots.actions" #actions="scope"><slot name="actions" v-bind="scope" /></template>
+    </STreeNode>
+  </ul>
+</template>
+
+<script setup lang="ts" generic="T extends object, K extends SelectionKey">
+import { computed, nextTick, provide, ref, watch } from 'vue'
+import { useOwnedAttrs } from '../../../internal/ownedAttrs'
+import { assertSelectionKey, selectionKeyToken } from '../_internal/useSelectionRoving'
+import STreeNode from '../_internal/STreeNode.vue'
+import {
+  TREE_RUNTIME_KEY,
+  type RegisteredTreeItem,
+  TreeItemRegistrationStore,
+  type TreeRuntime,
+} from '../_internal/treeRuntime'
+import { validateTreeModel } from './treeAdapter'
+import type {
+  STreeNodeContentScope,
+  STreeProps,
+  SelectionKey,
+  TreeActivationOrigin,
+  TreeNodeActivationEvent,
+  TreeNodeEvent,
+  TreeSelection,
+} from './types'
+
+defineOptions({ inheritAttrs: false })
+
+const props = withDefaults(defineProps<STreeProps<T, K>>(), {
+  expanded: () => new Set<K>(),
+  density: 'regular',
+  actionsLayout: 'reserved',
+  expandControl: 'button',
+  selectionRail: 'hidden',
+  rowVariant: 'default',
+})
+
+const emit = defineEmits<{
+  'update:selection': [selection: TreeSelection<K>]
+  'update:expanded': [expanded: Set<K>]
+  'node-activate': [event: TreeNodeActivationEvent<T, K>]
+  'node-select': [event: TreeNodeEvent<T, K>]
+  'node-expand': [event: TreeNodeEvent<T, K>]
+  'node-collapse': [event: TreeNodeEvent<T, K>]
+}>()
+
+defineSlots<{
+  'col-left': (props: STreeNodeContentScope<T, K>) => unknown
+  'col-center': (props: STreeNodeContentScope<T, K>) => unknown
+  'meta': (props: STreeNodeContentScope<T, K>) => unknown
+  'persistent-actions': (props: STreeNodeContentScope<T, K>) => unknown
+  'actions': (props: STreeNodeContentScope<T, K>) => unknown
+}>()
+
+const ownedAttrs = useOwnedAttrs({ component: 'STree', owner: 'role=tree root' })
+const treeRef = ref<HTMLElement | null>(null)
+const activeKey = ref<K>()
+const registeredItems = new TreeItemRegistrationStore<T, K>(() => treeRef.value)
+let typeahead = ''
+let typeaheadTimer: ReturnType<typeof setTimeout> | undefined
+
+function assertControlledKeyMembership(
+  key: K,
+  coordinate: 'selection.key' | 'selection.keys' | 'expanded',
+  inventory: ReadonlySet<K>,
+): void {
+  assertSelectionKey('STree', key, coordinate)
+  if (!inventory.has(key)) {
+    const keyDescription = selectionKeyToken('STree', key, coordinate)
+    throw new Error(
+      `STree: key ${keyDescription} из ${coordinate} отсутствует в текущем inventory модели. `
+      + `/ STree: ${coordinate} key ${keyDescription} is absent from the current model inventory.`,
+    )
+  }
+}
+
+function validateControlledState(inventory: ReadonlySet<K>): void {
+  const selection = props.selection
+  if (selection.mode === 'single' && selection.key !== null) {
+    assertControlledKeyMembership(selection.key, 'selection.key', inventory)
+  }
+  if (selection.mode === 'multiple') {
+    if (!(selection.keys instanceof Set)) {
+      throw new TypeError('STree: selection.keys must be a Set')
+    }
+    selection.keys.forEach((key) => assertControlledKeyMembership(key, 'selection.keys', inventory))
+  }
+  if (!(props.expanded instanceof Set)) {
+    throw new TypeError('STree: expanded must be a Set')
+  }
+  props.expanded.forEach((key) => assertControlledKeyMembership(key, 'expanded', inventory))
+}
+
+const validatedNodes = computed<readonly T[]>(() => {
+  const inventory = validateTreeModel(props.nodes, props.model)
+  validateControlledState(inventory)
+  return props.nodes
+})
+
+function registerTreeItem(item: RegisteredTreeItem<T, K>): void {
+  registeredItems.register(item)
+  if (activeKey.value === undefined && !item.disabled()) activeKey.value = item.key
+}
+
+function unregisterTreeItem(key: K): void {
+  registeredItems.unregister(key)
+  if (activeKey.value !== key) return
+  activeKey.value = undefined
+  void nextTick(() => {
+    activeKey.value = registeredItems.ordered().find((item) => !item.disabled())?.key
+  })
+}
+
+function visibleItems(): RegisteredTreeItem<T, K>[] {
+  return registeredItems.ordered()
+}
+
+async function focusItem(item: RegisteredTreeItem<T, K> | undefined): Promise<void> {
+  if (!item || item.disabled()) return
+  activeKey.value = item.key
+  await nextTick()
+  item.element.focus()
+}
+
+function handleTreeItemKeydown(item: RegisteredTreeItem<T, K>, event: KeyboardEvent): void {
+  const items = visibleItems().filter((candidate) => !candidate.disabled())
+  const index = items.findIndex((candidate) => candidate.key === item.key)
+  if (event.key === 'ArrowDown') {
+    event.preventDefault()
+    void focusItem(items[index + 1])
+    return
+  }
+  if (event.key === 'ArrowUp') {
+    event.preventDefault()
+    void focusItem(items[index - 1])
+    return
+  }
+  if (event.key === 'Home') {
+    event.preventDefault()
+    void focusItem(items[0])
+    return
+  }
+  if (event.key === 'End') {
+    event.preventDefault()
+    void focusItem(items.at(-1))
+    return
+  }
+  if (event.key === 'ArrowRight' && item.hasChildren()) {
+    event.preventDefault()
+    if (!item.expanded()) item.toggle()
+    else void focusItem(items.find((candidate) => candidate.parentKey === item.key))
+    return
+  }
+  if (event.key === 'ArrowLeft') {
+    event.preventDefault()
+    if (item.hasChildren() && item.expanded()) item.toggle()
+    else if (item.parentKey !== undefined) void focusItem(registeredItems.get(item.parentKey))
+    return
+  }
+  if (event.key === 'Enter' || event.key === ' ') {
+    event.preventDefault()
+    if (event.key === ' ' && props.selection.mode === 'multiple') item.select()
+    else item.activate('keyboard')
+    return
+  }
+  if (event.key.length !== 1 || event.ctrlKey || event.metaKey || event.altKey) return
+
+  typeahead += event.key.toLocaleLowerCase()
+  if (typeaheadTimer !== undefined) clearTimeout(typeaheadTimer)
+  typeaheadTimer = setTimeout(() => { typeahead = '' }, 500)
+  const ordered = [...items.slice(index + 1), ...items.slice(0, index + 1)]
+  void focusItem(ordered.find((candidate) =>
+    props.model.label(candidate.node).toLocaleLowerCase().startsWith(typeahead),
+  ))
+}
+
+function collectMultipleKeys(node: T): K[] {
+  if (props.model.disabled(node)) return []
+  const behavior = props.model.multipleSelection(node)
+  if (behavior === 'disabled') return []
+  if (behavior === 'self') return [props.model.key(node)]
+  const descendantKeys = props.model.children(node).flatMap((child) => collectMultipleKeys(child))
+  return behavior === 'self-and-descendants'
+    ? [props.model.key(node), ...descendantKeys]
+    : descendantKeys
+}
+
+function handleNodeSelect(node: T): void {
+  if (props.model.disabled(node) || props.selection.mode !== 'single') return
+  const key = props.model.key(node)
+  const nextKey = props.selection.key === key ? null : key
+  emit('update:selection', { mode: 'single', key: nextKey })
+  emit('node-select', { node, key })
+}
+
+function handleNodeActivate(node: T, origin: TreeActivationOrigin): void {
+  if (props.model.disabled(node) || props.model.children(node).length > 0) return
+  emit('node-activate', { node, key: props.model.key(node), origin })
+}
+
+function handleNodeCheck(node: T): void {
+  if (props.selection.mode !== 'multiple') return
+  const keys = collectMultipleKeys(node)
+  if (keys.length === 0) return
+
+  const nextKeys = new Set(props.selection.keys)
+  const allSelected = keys.every((key) => nextKeys.has(key))
+  for (const key of keys) {
+    if (allSelected) nextKeys.delete(key)
+    else nextKeys.add(key)
+  }
+  emit('update:selection', { mode: 'multiple', keys: nextKeys })
+}
+
+function handleNodeToggle(node: T): void {
+  const key = props.model.key(node)
+  const nextExpanded = new Set(props.expanded)
+  const event = { node, key }
+  if (nextExpanded.has(key)) {
+    nextExpanded.delete(key)
+    emit('node-collapse', event)
+  } else {
+    nextExpanded.add(key)
+    emit('node-expand', event)
+  }
+  emit('update:expanded', nextExpanded)
+}
+
+const runtime: TreeRuntime<T, K> = {
+  get model() { return props.model },
+  selection: computed(() => props.selection),
+  expanded: computed(() => props.expanded),
+  density: computed(() => props.density),
+  actionsLayout: computed(() => props.actionsLayout),
+  expandControl: computed(() => props.expandControl),
+  selectionRail: computed(() => props.selectionRail),
+  rowVariant: computed(() => props.rowVariant),
+  activeKey,
+  activateNode: handleNodeActivate,
+  selectNode: handleNodeSelect,
+  toggleNode: handleNodeToggle,
+  checkNode: handleNodeCheck,
+  multipleKeys: collectMultipleKeys,
+  register: registerTreeItem,
+  unregister: unregisterTreeItem,
+  handleItemKeydown: handleTreeItemKeydown,
+}
+
+provide(TREE_RUNTIME_KEY, runtime)
+
+watch(validatedNodes, (nodes) => {
+  if (activeKey.value !== undefined) return
+  const firstEnabled = nodes.find((node) => !props.model.disabled(node))
+  activeKey.value = firstEnabled === undefined ? undefined : props.model.key(firstEnabled)
+}, { immediate: true })
+</script>
+
+<style lang="postcss" src="./STree.css"></style>

package/src/components/shared/complex/treeAdapter.ts

@@ -0,0 +1,210 @@
+import {
+  assertSelectionKey,
+  selectionKeyToken,
+  validateSelectionIdentities,
+  type SelectionIdentity,
+  type SelectionKey,
+} from '../_internal/useSelectionRoving'
+import type { TreeModel } from './types'
+
+export interface FlatTreeAdapter<T extends object, K extends SelectionKey> {
+  key(node: T): K
+  parentKey(node: T): K | null
+  attachChildren(node: T, children: readonly T[]): T
+}
+
+function describeKey(key: SelectionKey): string {
+  return selectionKeyToken('tree adapter', key, 'diagnostic key')
+}
+
+/**
+ * Строит иерархию из плоских доменных данных. / Builds a hierarchy from flat domain data.
+ *
+ * Adapter не угадывает поля, не клонирует данные spread-оператором и не
+ * исправляет orphan/cycle payload. Любое нарушение даёт координатную ошибку.
+ */
+export function buildTreeFromFlat<T extends object, K extends SelectionKey>(
+  nodes: readonly T[],
+  adapter: FlatTreeAdapter<T, K>,
+): readonly T[] {
+  if (!Array.isArray(nodes)) {
+    throw new TypeError('buildTreeFromFlat.nodes: expected an array')
+  }
+
+  const entries = nodes.map((node, index) => {
+    const coordinate = `buildTreeFromFlat.nodes[${index}]`
+    const key = adapter.key(node)
+    assertSelectionKey('buildTreeFromFlat', key, `${coordinate}.key`)
+    return {
+      node,
+      key,
+      parentKey: adapter.parentKey(node),
+      coordinate,
+      children: [] as T[],
+    }
+  })
+  const byKey = new Map<K, (typeof entries)[number]>()
+
+  validateSelectionIdentities(
+    'buildTreeFromFlat',
+    entries.map((entry) => ({ key: entry.key, coordinate: `${entry.coordinate}.key` })),
+  )
+
+  for (const entry of entries) {
+    byKey.set(entry.key, entry)
+  }
+
+  for (const entry of entries) {
+    if (entry.parentKey === null) continue
+    assertSelectionKey('buildTreeFromFlat', entry.parentKey, `${entry.coordinate}.parentKey`)
+    if (entry.parentKey === entry.key) {
+      throw new TypeError(`${entry.coordinate}: node ${describeKey(entry.key)} cannot be its own parent`)
+    }
+    if (!byKey.has(entry.parentKey)) {
+      throw new TypeError(
+        `${entry.coordinate}: parent ${describeKey(entry.parentKey)} does not exist in the flat input`,
+      )
+    }
+  }
+
+  for (const entry of entries) {
+    const path = new Set<K>([entry.key])
+    let parentKey = entry.parentKey
+    while (parentKey !== null) {
+      if (path.has(parentKey)) {
+        throw new TypeError(
+          `${entry.coordinate}: parent chain contains a cycle at ${describeKey(parentKey)}`,
+        )
+      }
+      path.add(parentKey)
+      const parent = byKey.get(parentKey)
+      if (!parent) {
+        throw new TypeError(`${entry.coordinate}: parent chain is incomplete at ${describeKey(parentKey)}`)
+      }
+      parentKey = parent.parentKey
+    }
+  }
+
+  const roots: T[] = []
+  for (const entry of entries) {
+    if (entry.parentKey === null) {
+      roots.push(entry.node)
+      continue
+    }
+    const parent = byKey.get(entry.parentKey)
+    if (!parent) {
+      throw new TypeError(`${entry.coordinate}: parent ${describeKey(entry.parentKey)} is unavailable`)
+    }
+    parent.children.push(entry.node)
+  }
+
+  return roots.map((root) => {
+    const rootEntry = byKey.get(adapter.key(root))
+    if (!rootEntry) {
+      throw new TypeError('buildTreeFromFlat: root is absent from the validated key index')
+    }
+    return attachTreeChildren(rootEntry, byKey, adapter)
+  })
+}
+
+function attachTreeChildren<T extends object, K extends SelectionKey>(
+  entry: { readonly node: T; readonly key: K; readonly children: readonly T[] },
+  byKey: ReadonlyMap<K, { readonly node: T; readonly key: K; readonly children: readonly T[] }>,
+  adapter: FlatTreeAdapter<T, K>,
+): T {
+  const children = entry.children.map((child) => {
+    const childEntry = byKey.get(adapter.key(child))
+    if (!childEntry) {
+      throw new TypeError('buildTreeFromFlat: child is absent from the validated key index')
+    }
+    return attachTreeChildren(childEntry, byKey, adapter)
+  })
+  return adapter.attachChildren(entry.node, children)
+}
+
+function readModelValue<R>(
+  coordinate: string,
+  field: string,
+  reader: () => R,
+): R {
+  try {
+    return reader()
+  } catch (error) {
+    throw new TypeError(`STree: model.${field} failed at ${coordinate}`, { cause: error })
+  }
+}
+
+/** Проверяет точный runtime-контракт дерева. / Validates the exact runtime tree contract. */
+export function validateTreeModel<T extends object, K extends SelectionKey>(
+  nodes: readonly T[],
+  model: TreeModel<T, K>,
+): ReadonlySet<K> {
+  if (!Array.isArray(nodes)) {
+    throw new TypeError('STree: nodes must be an array')
+  }
+
+  const identities: SelectionIdentity<K>[] = []
+  const visitedNodes = new Set<T>()
+  const activeNodes = new Set<T>()
+
+  const visit = (node: T, coordinate: string): void => {
+    if (typeof node !== 'object' || node === null) {
+      throw new TypeError(`STree: node must be an object at ${coordinate}`)
+    }
+    if (activeNodes.has(node)) {
+      throw new TypeError(`STree: cyclic child reference at ${coordinate}`)
+    }
+    if (visitedNodes.has(node)) {
+      throw new TypeError(`STree: the same node object is referenced more than once at ${coordinate}`)
+    }
+
+    activeNodes.add(node)
+    visitedNodes.add(node)
+
+    const key = readModelValue(coordinate, 'key', () => model.key(node))
+    assertSelectionKey('STree', key, `${coordinate}.key`)
+    identities.push({ key, coordinate: `${coordinate}.key` })
+
+    const label = readModelValue(coordinate, 'label', () => model.label(node))
+    if (typeof label !== 'string' || label.trim().length === 0) {
+      throw new TypeError(`STree: model.label must return a non-empty string at ${coordinate}`)
+    }
+
+    const children = readModelValue(coordinate, 'children', () => model.children(node))
+    if (!Array.isArray(children)) {
+      throw new TypeError(`STree: model.children must return an array at ${coordinate}`)
+    }
+
+    const disabled = readModelValue(coordinate, 'disabled', () => model.disabled(node))
+    if (typeof disabled !== 'boolean') {
+      throw new TypeError(`STree: model.disabled must return a boolean at ${coordinate}`)
+    }
+
+    const icon = readModelValue(coordinate, 'icon', () => model.icon(node))
+    if (
+      icon !== undefined
+      && typeof icon !== 'function'
+      && (typeof icon !== 'object' || icon === null)
+    ) {
+      throw new TypeError(`STree: model.icon must return a Vue component or undefined at ${coordinate}`)
+    }
+
+    const multipleSelection = readModelValue(
+      coordinate,
+      'multipleSelection',
+      () => model.multipleSelection(node),
+    )
+    if (!['self', 'descendants', 'self-and-descendants', 'disabled'].includes(multipleSelection)) {
+      throw new TypeError(
+        `STree: model.multipleSelection returned an unsupported value at ${coordinate}`,
+      )
+    }
+
+    children.forEach((child, index) => visit(child, `${coordinate}.children[${index}]`))
+    activeNodes.delete(node)
+  }
+
+  nodes.forEach((node, index) => visit(node, `nodes[${index}]`))
+  validateSelectionIdentities('STree', identities)
+  return new Set(identities.map((identity) => identity.key))
+}