@pgcorp/ui-kit 0.1.0

package/src/internal/runtimeContract.ts

@@ -0,0 +1,194 @@
+export interface BoundedNumberDomain {
+  minimum: number
+  maximum: number
+}
+
+const ASCII_WHITESPACE_PATTERN = /[\t\n\f\r ]/u
+
+function describeRuntimeValue(value: unknown): string {
+  if (typeof value === 'string') return JSON.stringify(value)
+  if (typeof value === 'number') return `number(${String(value)})`
+  if (typeof value === 'bigint') return `bigint(${String(value)})`
+  if (typeof value === 'boolean') return `boolean(${String(value)})`
+  if (typeof value === 'undefined') return 'undefined'
+  if (typeof value === 'symbol') return `symbol(${value.description ?? ''})`
+  if (typeof value === 'function') return 'function'
+  if (value === null) return 'null'
+  return Array.isArray(value) ? 'array' : 'object'
+}
+
+function assertBoundedDomain(
+  owner: string,
+  coordinate: string,
+  domain: BoundedNumberDomain,
+  integer: boolean,
+): void {
+  const validNumbers = Number.isFinite(domain.minimum) && Number.isFinite(domain.maximum)
+  const validIntegerBounds = !integer
+    || (Number.isInteger(domain.minimum) && Number.isInteger(domain.maximum))
+  if (validNumbers && validIntegerBounds && domain.minimum <= domain.maximum) return
+
+  const russianKind = integer ? 'целыми числами' : 'конечными числами'
+  const englishKind = integer ? 'integers' : 'finite numbers'
+  throw new TypeError(
+    `runtimeContract: границы domain для ${owner}.${coordinate} должны быть ${russianKind}, `
+    + `где minimum <= maximum; получено minimum=${describeRuntimeValue(domain.minimum)}, `
+    + `maximum=${describeRuntimeValue(domain.maximum)}. / runtimeContract: domain bounds for `
+    + `${owner}.${coordinate} must be ${englishKind} with minimum <= maximum; received `
+    + `minimum=${describeRuntimeValue(domain.minimum)}, maximum=${describeRuntimeValue(domain.maximum)}.`,
+  )
+}
+
+function assertExactStringDomain(
+  owner: string,
+  coordinate: string,
+  allowed: readonly string[],
+): void {
+  const uniqueValues = new Set(allowed)
+  if (
+    allowed.length > 0
+    && uniqueValues.size === allowed.length
+    && allowed.every((value) => value.trim().length > 0)
+  ) return
+
+  throw new TypeError(
+    `runtimeContract: domain для ${owner}.${coordinate} должен содержать непустой уникальный список строк. `
+    + `/ runtimeContract: domain for ${owner}.${coordinate} must contain a non-empty unique string list.`,
+  )
+}
+
+/**
+ * Проверяет непустую строку без trim/coercion и возвращает исходное значение.
+ * Validates a non-empty string without trimming/coercion and returns the original value.
+ */
+export function validateNonEmptyString(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+): string {
+  if (typeof value === 'string' && value.trim().length > 0) return value
+  const received = describeRuntimeValue(value)
+  throw new TypeError(
+    `${owner}: ${coordinate} должен быть непустой строкой; получено ${received}. `
+    + `/ ${owner}: ${coordinate} must be a non-empty string; received ${received}.`,
+  )
+}
+
+/**
+ * Проверяет boolean без truthy/falsy coercion.
+ * Validates a boolean without truthy/falsy coercion.
+ */
+export function validateBoolean(owner: string, coordinate: string, value: unknown): boolean {
+  if (typeof value === 'boolean') return value
+  const received = describeRuntimeValue(value)
+  throw new TypeError(
+    `${owner}: ${coordinate} должен быть boolean; получено ${received}. `
+    + `/ ${owner}: ${coordinate} must be a boolean; received ${received}.`,
+  )
+}
+
+/**
+ * Проверяет DOM id по HTML-контракту: непустая строка без ASCII whitespace.
+ * Validates an HTML DOM id: a non-empty string without ASCII whitespace.
+ */
+export function validateDomId(owner: string, coordinate: string, value: unknown): string {
+  if (typeof value === 'string' && value.length > 0 && !ASCII_WHITESPACE_PATTERN.test(value)) {
+    return value
+  }
+  const received = describeRuntimeValue(value)
+  throw new TypeError(
+    `${owner}: ${coordinate} должен быть непустым DOM id без ASCII-пробелов; получено ${received}. `
+    + `/ ${owner}: ${coordinate} must be a non-empty DOM id without ASCII whitespace; `
+    + `received ${received}.`,
+  )
+}
+
+/**
+ * Возвращает generated DOM id только при отсутствии явного значения и валидирует обе ветки.
+ * Returns a generated DOM id only when the explicit value is absent and validates both branches.
+ */
+export function resolveOptionalDomId(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+  generatedValue: unknown,
+): string {
+  return value === undefined
+    ? validateDomId(owner, `generated ${coordinate}`, generatedValue)
+    : validateDomId(owner, coordinate, value)
+}
+
+/**
+ * Проверяет exact string enum и сохраняет его literal union в return type.
+ * Validates an exact string enum and preserves its literal union in the return type.
+ */
+export function validateExactString<const Allowed extends readonly string[]>(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+  allowed: Allowed,
+): Allowed[number] {
+  assertExactStringDomain(owner, coordinate, allowed)
+  if (typeof value === 'string' && allowed.includes(value)) return value as Allowed[number]
+
+  const expected = `[${allowed.map((candidate) => JSON.stringify(candidate)).join(', ')}]`
+  const received = describeRuntimeValue(value)
+  throw new TypeError(
+    `${owner}: ${coordinate} должен быть одним из ${expected}; получено ${received}. `
+    + `/ ${owner}: ${coordinate} must be one of ${expected}; received ${received}.`,
+  )
+}
+
+/**
+ * Проверяет конечное число в inclusive domain без coercion.
+ * Validates a finite number in an inclusive domain without coercion.
+ */
+export function validateBoundedNumber(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+  domain: BoundedNumberDomain,
+): number {
+  assertBoundedDomain(owner, coordinate, domain, false)
+  if (
+    typeof value === 'number'
+    && Number.isFinite(value)
+    && value >= domain.minimum
+    && value <= domain.maximum
+  ) return value
+
+  const received = describeRuntimeValue(value)
+  throw new TypeError(
+    `${owner}: ${coordinate} должен быть конечным числом в диапазоне `
+    + `[${domain.minimum}, ${domain.maximum}]; получено ${received}. / ${owner}: ${coordinate} `
+    + `must be a finite number in the inclusive range [${domain.minimum}, ${domain.maximum}]; `
+    + `received ${received}.`,
+  )
+}
+
+/**
+ * Проверяет целое число в inclusive domain без coercion.
+ * Validates an integer in an inclusive domain without coercion.
+ */
+export function validateBoundedInteger(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+  domain: BoundedNumberDomain,
+): number {
+  assertBoundedDomain(owner, coordinate, domain, true)
+  if (
+    typeof value === 'number'
+    && Number.isInteger(value)
+    && value >= domain.minimum
+    && value <= domain.maximum
+  ) return value
+
+  const received = describeRuntimeValue(value)
+  throw new TypeError(
+    `${owner}: ${coordinate} должен быть целым числом в диапазоне `
+    + `[${domain.minimum}, ${domain.maximum}]; получено ${received}. / ${owner}: ${coordinate} `
+    + `must be an integer in the inclusive range [${domain.minimum}, ${domain.maximum}]; `
+    + `received ${received}.`,
+  )
+}

package/src/internal/runtimeTheme.ts

@@ -0,0 +1,159 @@
+import { onBeforeUnmount, onMounted, readonly, ref, type DeepReadonly, type Ref } from 'vue'
+import {
+  isThemePreference,
+  themeVariants,
+  type ThemeMode,
+  type ThemePreference,
+  type ThemeVariant,
+} from '../theme'
+
+/**
+ * Текущее декларативное состояние темы документа.
+ * Current declarative document-theme state.
+ */
+export interface RuntimeThemeState {
+  /** Точное значение `data-theme`; `null` только при отсутствии явной темы. / Exact `data-theme`; `null` only when no explicit theme is applied. */
+  readonly dataTheme: ThemePreference | null
+  /** Нормализованный режим для runtime adapter. / Normalized mode for a runtime adapter. */
+  readonly mode: ThemeMode
+}
+
+type RuntimeThemeListener = (state: RuntimeThemeState) => void
+
+interface DocumentThemeRuntime {
+  readonly document: Document
+  readonly listeners: Set<RuntimeThemeListener>
+  observer: MutationObserver | null
+  state: RuntimeThemeState
+}
+
+const runtimes = new WeakMap<Document, DocumentThemeRuntime>()
+
+const themeVariantByDataTheme = new Map<ThemePreference, ThemeVariant>(
+  themeVariants.map((variant): [ThemePreference, ThemeVariant] => [variant.dataTheme, variant]),
+)
+
+const statesEqual = (left: RuntimeThemeState, right: RuntimeThemeState): boolean => (
+  left.dataTheme === right.dataTheme && left.mode === right.mode
+)
+
+/**
+ * Читает theme contract документа без подписки и DOM-мутаций.
+ * Reads the document theme contract without subscribing or mutating DOM.
+ */
+export function readRuntimeTheme(targetDocument?: Document): RuntimeThemeState {
+  if (targetDocument === undefined) return { dataTheme: null, mode: 'light' }
+  const root = targetDocument.documentElement
+  const rawDataTheme = root.getAttribute('data-theme')
+  if (rawDataTheme === null) {
+    if (root.classList.contains('dark')) {
+      throw new Error('UI-kit runtime theme: class="dark" требует canonical data-theme.')
+    }
+    return { dataTheme: null, mode: 'light' }
+  }
+  const dataTheme = rawDataTheme
+  if (!isThemePreference(dataTheme)) {
+    throw new TypeError(`UI-kit runtime theme: неизвестный data-theme "${rawDataTheme}".`)
+  }
+  const variant = themeVariantByDataTheme.get(dataTheme)
+  if (variant === undefined) {
+    throw new Error(
+      `UI-kit runtime theme: data-theme="${dataTheme}" отсутствует в canonical theme registry.`,
+    )
+  }
+  const mode = variant.mode
+  const hasDarkClass = root.classList.contains('dark')
+  if (mode === 'dark' && !hasDarkClass) {
+    throw new Error(`UI-kit runtime theme: data-theme="${dataTheme}" требует class="dark".`)
+  }
+  if (mode === 'light' && hasDarkClass) {
+    throw new Error(`UI-kit runtime theme: data-theme="${dataTheme}" конфликтует с class="dark".`)
+  }
+  return {
+    dataTheme,
+    mode,
+  }
+}
+
+const refreshRuntime = (runtime: DocumentThemeRuntime): void => {
+  const nextState = readRuntimeTheme(runtime.document)
+  if (statesEqual(runtime.state, nextState)) return
+  runtime.state = nextState
+  for (const listener of runtime.listeners) listener(nextState)
+}
+
+const createRuntime = (targetDocument: Document): DocumentThemeRuntime => ({
+  document: targetDocument,
+  listeners: new Set(),
+  observer: null,
+  state: readRuntimeTheme(targetDocument),
+})
+
+const startRuntime = (runtime: DocumentThemeRuntime): void => {
+  if (runtime.observer || typeof MutationObserver === 'undefined') return
+  runtime.observer = new MutationObserver(() => refreshRuntime(runtime))
+  runtime.observer.observe(runtime.document.documentElement, {
+    attributes: true,
+    attributeFilter: ['class', 'data-theme'],
+  })
+}
+
+const stopRuntime = (runtime: DocumentThemeRuntime): void => {
+  if (runtime.observer !== null) runtime.observer.disconnect()
+  runtime.observer = null
+  runtimes.delete(runtime.document)
+}
+
+/**
+ * Подписывает runtime-интеграцию на единый per-document theme owner.
+ * Subscribes a runtime integration to the single per-document theme owner.
+ */
+export function subscribeRuntimeTheme(
+  listener: RuntimeThemeListener,
+  targetDocument?: Document,
+): () => void {
+  if (targetDocument === undefined) {
+    listener(readRuntimeTheme())
+    return () => undefined
+  }
+
+  let runtime = runtimes.get(targetDocument)
+  if (runtime === undefined) {
+    runtime = createRuntime(targetDocument)
+    runtimes.set(targetDocument, runtime)
+  }
+  const subscribedRuntime = runtime
+  subscribedRuntime.listeners.add(listener)
+  listener(subscribedRuntime.state)
+  startRuntime(subscribedRuntime)
+
+  let subscribed = true
+  return () => {
+    if (!subscribed) return
+    subscribed = false
+    subscribedRuntime.listeners.delete(listener)
+    if (subscribedRuntime.listeners.size === 0) stopRuntime(subscribedRuntime)
+  }
+}
+
+/**
+ * Vue lifecycle adapter для единого runtime theme owner.
+ * Vue lifecycle adapter for the canonical runtime theme owner.
+ */
+export function useRuntimeTheme(): DeepReadonly<Ref<RuntimeThemeState>> {
+  const targetDocument = typeof document === 'undefined' ? undefined : document
+  const state = ref<RuntimeThemeState>(readRuntimeTheme(targetDocument))
+  let unsubscribe: (() => void) | null = null
+
+  onMounted(() => {
+    unsubscribe = subscribeRuntimeTheme((nextState) => {
+      state.value = nextState
+    }, targetDocument)
+  })
+  onBeforeUnmount(() => {
+    if (unsubscribe !== null) unsubscribe()
+    unsubscribe = null
+  })
+
+  return readonly(state)
+}

package/src/internal/semanticSizing.ts

@@ -0,0 +1,60 @@
+import { validateExactString } from './runtimeContract'
+
+const SCROLLABLE_VIEWPORT_MAX_BLOCK_SIZES = ['none', 'sm', 'md', 'lg'] as const
+const EXPANDED_CONTENT_MAX_BLOCK_SIZES = ['sm', 'md', 'lg'] as const
+const TABLE_COLUMN_INLINE_SIZES = ['auto', 'xs', 'sm', 'md', 'lg', 'xl', 'fill'] as const
+const TABLE_COLUMN_MIN_INLINE_SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const
+
+/**
+ * Максимальный block-size прокручиваемого viewport; none сохраняет естественный flow.
+ * Maximum block size for a scroll viewport; none preserves natural flow.
+ */
+export type ScrollableViewportMaxBlockSize = typeof SCROLLABLE_VIEWPORT_MAX_BLOCK_SIZES[number]
+
+/**
+ * Максимальный block-size раскрытого текстового content region.
+ * Maximum block size for an expanded textual content region.
+ */
+export type ExpandedContentMaxBlockSize = typeof EXPANDED_CONTENT_MAX_BLOCK_SIZES[number]
+
+/** Семантическая ширина столбца таблицы. / Semantic table-column inline size. */
+export type TableColumnInlineSize = typeof TABLE_COLUMN_INLINE_SIZES[number]
+
+/** Семантическая минимальная ширина столбца таблицы. / Semantic table-column minimum inline size. */
+export type TableColumnMinInlineSize = typeof TABLE_COLUMN_MIN_INLINE_SIZES[number]
+
+/** Проверяет semantic scroll viewport size без CSS-length escape. / Validates a semantic scroll viewport size without a CSS-length escape. */
+export function validateScrollableViewportMaxBlockSize(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+): ScrollableViewportMaxBlockSize {
+  return validateExactString(owner, coordinate, value, SCROLLABLE_VIEWPORT_MAX_BLOCK_SIZES)
+}
+
+/** Проверяет semantic expanded-content size без CSS-length escape. / Validates a semantic expanded-content size without a CSS-length escape. */
+export function validateExpandedContentMaxBlockSize(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+): ExpandedContentMaxBlockSize {
+  return validateExactString(owner, coordinate, value, EXPANDED_CONTENT_MAX_BLOCK_SIZES)
+}
+
+/** Проверяет semantic column width без CSS-length escape. / Validates semantic column width without a CSS-length escape. */
+export function validateTableColumnInlineSize(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+): TableColumnInlineSize {
+  return validateExactString(owner, coordinate, value, TABLE_COLUMN_INLINE_SIZES)
+}
+
+/** Проверяет semantic minimum column width без CSS-length escape. / Validates semantic minimum column width without a CSS-length escape. */
+export function validateTableColumnMinInlineSize(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+): TableColumnMinInlineSize {
+  return validateExactString(owner, coordinate, value, TABLE_COLUMN_MIN_INLINE_SIZES)
+}

package/src/internal/useMenuLayer.ts

@@ -0,0 +1,129 @@
+import { nextTick, onBeforeUnmount, ref, type Ref } from 'vue'
+import { useFloatingPosition } from '../composables/useFloatingPosition'
+import { findFocusableOwner, findRelativeTabTarget } from './focusNavigation'
+import { registerLayer, type LayerRegistration } from './layerStack'
+
+export type MenuAnchor =
+  | { type: 'element'; element: HTMLElement; align: 'left' | 'right'; placement?: 'bottom' | 'inline' }
+  | { type: 'point'; x: number; y: number }
+
+export type MenuCloseReason = 'escape' | 'outside' | 'programmatic' | 'selection' | 'trigger'
+
+const VIEWPORT_PADDING = 5
+
+const pointRect = (x: number, y: number): DOMRect => ({
+  x,
+  y,
+  left: x,
+  right: x,
+  top: y,
+  bottom: y,
+  width: 0,
+  height: 0,
+  toJSON: () => ({ x, y }),
+}) as DOMRect
+
+/** Управляет общей lifecycle/focus границей menu поверх canonical floating geometry. / Owns menu lifecycle and focus over canonical floating geometry. */
+export function useMenuLayer(
+  layerRef: Ref<HTMLElement | null>,
+  options: { onDismiss?: (reason: 'escape' | 'outside') => void } = {},
+) {
+  const isOpen = ref(false)
+  const zIndex = ref('var(--s-layer-floating)')
+  let anchor: MenuAnchor | null = null
+  let focusAnchor: HTMLElement | null = null
+  let registration: LayerRegistration | null = null
+
+  function close(reason: MenuCloseReason = 'programmatic'): void {
+    if (!isOpen.value && !registration) return
+    isOpen.value = false
+    registration?.unregister({ restoreFocus: reason !== 'outside' })
+    registration = null
+    anchor = null
+    focusAnchor = null
+    zIndex.value = 'var(--s-layer-floating)'
+  }
+
+  function closeForTab(event: KeyboardEvent): void {
+    const reference = focusAnchor
+    if (!reference) {
+      close('outside')
+      return
+    }
+    const scope = registration?.focusScope() ?? document
+    const target = findRelativeTabTarget(reference, scope, layerRef.value, event.shiftKey)
+    event.preventDefault()
+    close('outside')
+    if (target) nextTick(() => target.focus())
+  }
+
+  const anchorElement = (): HTMLElement | null => anchor?.type === 'element' ? anchor.element : null
+  const anchorRect = (): DOMRect | null => {
+    if (!anchor) return null
+    if (anchor.type === 'point') return pointRect(anchor.x, anchor.y)
+    if (!anchor.element.isConnected) {
+      close('outside')
+      return null
+    }
+    return anchor.element.getBoundingClientRect()
+  }
+
+  const {
+    coordinates: position,
+    updatePosition: positionLayer,
+  } = useFloatingPosition({
+    active: isOpen,
+    placement: () => anchor?.type === 'element' && anchor.placement === 'inline'
+      ? (anchor.align === 'right' ? 'left-start' : 'right-start')
+      : anchor?.type === 'element' && anchor.align === 'right' ? 'bottom-end' : 'bottom-start',
+    anchorElement,
+    anchorRect,
+    panelRef: layerRef,
+    offset: () => 0,
+    boundaryPadding: () => VIEWPORT_PADDING,
+    flip: () => true,
+    shift: () => true,
+    widthMatch: () => 'none',
+    zIndex: () => zIndex.value,
+    scrollStrategy: 'reposition',
+  })
+
+  async function open(nextAnchor: MenuAnchor, focusTarget?: HTMLElement | null): Promise<void> {
+    if (isOpen.value) close('outside')
+    if (nextAnchor.type === 'element' && findFocusableOwner(nextAnchor.element) !== nextAnchor.element) {
+      throw new Error('useMenuLayer: element anchor must be the canonical focusable owner')
+    }
+    anchor = nextAnchor
+    const restoreTarget = findFocusableOwner(focusTarget ?? null)
+      ?? findFocusableOwner(document.activeElement)
+    focusAnchor = nextAnchor.type === 'element' ? nextAnchor.element : restoreTarget
+    isOpen.value = true
+    registration = registerLayer({
+      kind: 'menu',
+      root: () => layerRef.value,
+      anchor: () => nextAnchor.type === 'element' ? nextAnchor.element : restoreTarget,
+      restoreTarget,
+      requestDismiss: (reason) => {
+        const closeReason = reason === 'escape' ? 'escape' : 'outside'
+        close(closeReason)
+        options.onDismiss?.(closeReason)
+      },
+    })
+    zIndex.value = registration.zIndex
+    await nextTick()
+    if (!isOpen.value) return
+    if (!layerRef.value) {
+      close('outside')
+      throw new Error('useMenuLayer: layer element is unavailable after opening')
+    }
+    positionLayer()
+  }
+
+  function toggle(nextAnchor: MenuAnchor, focusTarget?: HTMLElement | null): void {
+    if (isOpen.value) close('trigger')
+    else void open(nextAnchor, focusTarget)
+  }
+
+  onBeforeUnmount(() => close('outside'))
+  return { isOpen, position, zIndex, open, close, closeForTab, toggle, positionLayer }
+}

package/src/stores/useNotifierStore.ts

@@ -0,0 +1,69 @@
+import { defineStore } from 'pinia'
+import { v4 as uuidv4 } from 'uuid'
+import type { FeedbackSeverity } from '../internal/feedbackPresentation'
+
+/** Severity уведомления использует канонический feedback-контракт. / Notification severity uses the canonical feedback contract. */
+export type Severity = FeedbackSeverity
+
+export interface Notification {
+  id: string
+  severity: Severity
+  title?: string
+  message: string
+  duration?: number
+  createdAt: string
+}
+
+export type NotificationInput = Omit<Notification, 'id' | 'createdAt'>
+
+interface NotifierState {
+  notifications: Notification[]
+  history: Notification[]
+}
+
+const DEFAULT_NOTIFICATION_DURATION_MS = 2800
+const removalTimers = new Map<string, ReturnType<typeof setTimeout>>()
+
+function stopRemovalTimer(id: string): void {
+  const timer = removalTimers.get(id)
+  if (!timer) {
+    return
+  }
+  clearTimeout(timer)
+  removalTimers.delete(id)
+}
+
+export const useNotifierStore = defineStore('notifier', {
+  state: (): NotifierState => ({
+    notifications: [],
+    history: [],
+  }),
+  actions: {
+    add(notification: NotificationInput) {
+      const id = uuidv4()
+      const newNotification: Notification = {
+        id,
+        createdAt: new Date().toISOString(),
+        duration: DEFAULT_NOTIFICATION_DURATION_MS,
+        ...notification,
+      }
+
+      this.history.unshift(newNotification)
+      this.notifications.push(newNotification)
+
+      if (newNotification.duration) {
+        const removalTimer = setTimeout(() => {
+          this.remove(id)
+        }, newNotification.duration)
+        removalTimers.set(id, removalTimer)
+      }
+    },
+    remove(id: string) {
+      stopRemovalTimer(id)
+      this.notifications = this.notifications.filter((n) => n.id !== id)
+    },
+    clearHistory() {
+      this.history = []
+    },
+  },
+})

package/src/styles/reference.css

@@ -0,0 +1,4 @@
+@import "./tokens.css";
+@import "tailwindcss";
+@plugin "@tailwindcss/typography";
+@custom-variant dark (&:where(.dark, .dark *));