@pgcorp/ui-kit 0.1.0

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

@@ -0,0 +1,105 @@
+export type DialogSurfaceModalSize = 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'wide' | 'full'
+export type DialogSurfaceDrawerSize = 'sm' | 'md' | 'lg'
+export type DialogSurfaceTone = 'default' | 'subtle'
+export type DialogSurfaceScrollBehavior = 'page' | 'body'
+
+export interface ModalDialogSurfacePresentation {
+  kind: 'modal'
+  size: DialogSurfaceModalSize
+  fullscreen: boolean
+  surface: DialogSurfaceTone
+  scrollBehavior: DialogSurfaceScrollBehavior
+}
+
+export interface DrawerDialogSurfacePresentation {
+  kind: 'drawer'
+  size: DialogSurfaceDrawerSize
+  mobileFullScreen: boolean
+}
+
+export type DialogSurfacePresentation =
+  | ModalDialogSurfacePresentation
+  | DrawerDialogSurfacePresentation
+
+export type DialogSurfaceContractErrorCode =
+  | 'invalid-presentation'
+  | 'invalid-size'
+  | 'invalid-surface'
+  | 'invalid-scroll-behavior'
+
+export class DialogSurfaceContractError extends Error {
+  readonly code: DialogSurfaceContractErrorCode
+
+  constructor(code: DialogSurfaceContractErrorCode, message: string) {
+    super(message)
+    this.name = 'DialogSurfaceContractError'
+    this.code = code
+  }
+}
+
+const modalKeys = new Set(['kind', 'size', 'fullscreen', 'surface', 'scrollBehavior'])
+const drawerKeys = new Set(['kind', 'size', 'mobileFullScreen'])
+const modalSizes = new Set<DialogSurfaceModalSize>(['sm', 'md', 'lg', 'xl', '2xl', '3xl', 'wide', 'full'])
+const drawerSizes = new Set<DialogSurfaceDrawerSize>(['sm', 'md', 'lg'])
+const surfaceTones = new Set<DialogSurfaceTone>(['default', 'subtle'])
+const scrollBehaviors = new Set<DialogSurfaceScrollBehavior>(['page', 'body'])
+
+const assertExactKeys = (
+  presentation: Record<string, unknown>,
+  kind: DialogSurfacePresentation['kind'],
+  allowedKeys: ReadonlySet<string>,
+): void => {
+  const unexpectedKey = Object.keys(presentation).find((key) => !allowedKeys.has(key))
+  if (unexpectedKey) {
+    throw new DialogSurfaceContractError(
+      'invalid-presentation',
+      `SDialogSurface presentation kind="${kind}" содержит недопустимое поле ${unexpectedKey}`,
+    )
+  }
+}
+
+/**
+ * Проверяет закрытый discriminated contract приватной dialog surface без fallback-веток.
+ * Validates the private dialog surface discriminated contract without fallback branches.
+ */
+export function assertDialogSurfacePresentation(
+  presentation: DialogSurfacePresentation,
+): asserts presentation is DialogSurfacePresentation {
+  const candidate = presentation as unknown as Record<string, unknown>
+
+  if (candidate.kind === 'modal') {
+    assertExactKeys(candidate, 'modal', modalKeys)
+    if (!modalSizes.has(candidate.size as DialogSurfaceModalSize)) {
+      throw new DialogSurfaceContractError('invalid-size', `Недопустимый размер SModal: ${String(candidate.size)}`)
+    }
+    if (typeof candidate.fullscreen !== 'boolean') {
+      throw new DialogSurfaceContractError('invalid-presentation', 'SModal presentation требует boolean fullscreen')
+    }
+    if (!surfaceTones.has(candidate.surface as DialogSurfaceTone)) {
+      throw new DialogSurfaceContractError('invalid-surface', `Недопустимая поверхность SModal: ${String(candidate.surface)}`)
+    }
+    if (!scrollBehaviors.has(candidate.scrollBehavior as DialogSurfaceScrollBehavior)) {
+      throw new DialogSurfaceContractError(
+        'invalid-scroll-behavior',
+        `Недопустимый scroll behavior SModal: ${String(candidate.scrollBehavior)}`,
+      )
+    }
+    return
+  }
+
+  if (candidate.kind === 'drawer') {
+    assertExactKeys(candidate, 'drawer', drawerKeys)
+    if (!drawerSizes.has(candidate.size as DialogSurfaceDrawerSize)) {
+      throw new DialogSurfaceContractError('invalid-size', `Недопустимый размер SDrawer: ${String(candidate.size)}`)
+    }
+    if (typeof candidate.mobileFullScreen !== 'boolean') {
+      throw new DialogSurfaceContractError('invalid-presentation', 'SDrawer presentation требует boolean mobileFullScreen')
+    }
+    return
+  }
+
+  throw new DialogSurfaceContractError(
+    'invalid-presentation',
+    `Неизвестный kind SDialogSurface: ${String(candidate.kind)}`,
+  )
+}

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

@@ -0,0 +1,40 @@
+import type { Ref } from 'vue'
+
+import { getFocusableElements } from '../../../internal/focusNavigation'
+
+export function trapFocusInsidePanel(event: KeyboardEvent, panelRef: Ref<HTMLElement | null>, isOpen: boolean): void {
+  if (event.key !== 'Tab' || !isOpen) {
+    return
+  }
+
+  const panel = panelRef.value
+  if (!panel) {
+    return
+  }
+
+  const visibleFocusable = getFocusableElements(panel, { requireLayout: true })
+
+  if (visibleFocusable.length === 0) {
+    event.preventDefault()
+    panel.focus()
+    return
+  }
+
+  const firstElement = visibleFocusable[0]
+  const lastElement = visibleFocusable[visibleFocusable.length - 1]
+  const activeElement = document.activeElement as HTMLElement | null
+  const focusIsOutsideSequence = activeElement === panel || !panel.contains(activeElement)
+
+  if (event.shiftKey) {
+    if (activeElement === firstElement || focusIsOutsideSequence) {
+      event.preventDefault()
+      lastElement?.focus()
+    }
+    return
+  }
+
+  if (activeElement === lastElement || focusIsOutsideSequence) {
+    event.preventDefault()
+    firstElement?.focus()
+  }
+}

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

@@ -0,0 +1,16 @@
+import type { InjectionKey } from 'vue'
+
+export interface ListboxOptionRegistration {
+  token: string
+  element: HTMLElement
+  activate: () => void
+  disabled: () => boolean
+  label: () => string
+  selected: () => boolean
+}
+
+export interface ListboxContext {
+  register: (registration: ListboxOptionRegistration) => () => void
+}
+
+export const listboxContextKey: InjectionKey<ListboxContext> = Symbol('s-listbox-context')

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

@@ -0,0 +1,10 @@
+export type SMarkerTone = 'surface' | 'primary' | 'success' | 'blue' | 'sky' | 'indigo' | 'emerald' | 'green' | 'teal' | 'amber' | 'orange' | 'rose' | 'pink' | 'fuchsia' | 'cyan' | 'lime'
+export type SMarker = { tone: SMarkerTone } | { tone: 'custom'; color: `#${string}` }
+export type SCustomMarker = Extract<SMarker, { tone: 'custom' }>
+
+export function createCustomMarker(color: string): SCustomMarker {
+  if (!/^#[\da-f]{6}$/iu.test(color)) {
+    throw new Error('SMarker: custom color must be a six-digit hex value')
+  }
+  return { tone: 'custom', color: color as `#${string}` }
+}

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

@@ -0,0 +1,23 @@
+import type { InjectionKey, Ref } from 'vue'
+
+export type MenuDensity = 'compact' | 'comfortable'
+
+export interface MenuItemRegistration {
+  readonly entryId: string
+  readonly label: () => string
+  readonly hasSubmenu: () => boolean
+  readonly element: () => HTMLElement
+  readonly setTabStop: (active: boolean) => void
+  readonly focus: () => void
+  readonly isFocused: () => boolean
+  readonly ownsEventTarget: (target: EventTarget | null) => boolean
+  readonly activate: (event: KeyboardEvent) => void
+}
+
+export interface MenuContext {
+  density: Readonly<Ref<MenuDensity>>
+  register: (registration: MenuItemRegistration) => () => void
+}
+
+export const menuContextKey: InjectionKey<MenuContext> = Symbol('s-menu-context')
+export const menuDepthKey: InjectionKey<number> = Symbol('s-menu-depth')

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

@@ -0,0 +1,239 @@
+import { validateBoolean, validateNonEmptyString } from '../../../internal/runtimeContract'
+import { createCustomMarker, type SMarker } from './markerContract'
+import {
+  selectionKeyToken,
+  validateSelectionIdentities,
+  type SelectionKey,
+} from './useSelectionRoving'
+
+/** Одна типизированная option общего selection owner. / One typed option of the shared selection owner. */
+export interface SelectionOption<TKey extends SelectionKey = SelectionKey> {
+  value: TKey
+  label: string
+  title?: string
+  marker?: SMarker
+  disabled?: boolean
+}
+
+/** Группа options с собственной стабильной identity. / An option group with its own stable identity. */
+export interface SelectionOptionGroup<TKey extends SelectionKey = SelectionKey> {
+  groupId: string
+  label: string
+  options: readonly SelectionOption<TKey>[]
+}
+
+export type SelectionEntry<TKey extends SelectionKey = SelectionKey> =
+  | SelectionOption<TKey>
+  | SelectionOptionGroup<TKey>
+export type SelectionMode = 'single' | 'multiple'
+export type SelectionModelValue<
+  TKey extends SelectionKey,
+  TMode extends SelectionMode,
+> = TMode extends 'multiple' ? readonly TKey[] : TKey | null
+
+export interface ResolvedSelectionOption<TKey extends SelectionKey> {
+  option: SelectionOption<TKey>
+  token: string
+  coordinate: string
+}
+
+export type ResolvedSelectionEntry<TKey extends SelectionKey> =
+  | { kind: 'option'; record: ResolvedSelectionOption<TKey>; token: string }
+  | {
+    kind: 'group'
+    groupId: string
+    label: string
+    records: readonly ResolvedSelectionOption<TKey>[]
+    token: string
+  }
+
+export interface ResolvedSelectionInventory<TKey extends SelectionKey> {
+  entries: readonly ResolvedSelectionEntry<TKey>[]
+  options: readonly ResolvedSelectionOption<TKey>[]
+  optionsByToken: ReadonlyMap<string, ResolvedSelectionOption<TKey>>
+}
+
+const OPTION_KEYS = new Set(['value', 'label', 'title', 'marker', 'disabled'])
+const GROUP_KEYS = new Set(['groupId', 'label', 'options'])
+const MARKER_TONES = [
+  'surface', 'primary', 'success', 'blue', 'sky', 'indigo', 'emerald', 'green', 'teal',
+  'amber', 'orange', 'rose', 'pink', 'fuchsia', 'cyan', 'lime', 'custom',
+] as const
+
+function assertRecord(owner: string, coordinate: string, value: unknown): asserts value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new TypeError(`${owner}: ${coordinate} must be an option object or an option group`)
+  }
+}
+
+function assertExactKeys(
+  owner: string,
+  coordinate: string,
+  value: Record<string, unknown>,
+  keys: ReadonlySet<string>,
+): void {
+  const unsupported = Object.keys(value).find((key) => !keys.has(key))
+  if (unsupported !== undefined) {
+    throw new TypeError(`${owner}: ${coordinate}.${unsupported} is not part of the selection contract`)
+  }
+}
+
+/** Проверяет optional selection text без coercion. / Validates optional selection text without coercion. */
+export function validateOptionalSelectionString(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+): string | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'string') {
+    throw new TypeError(`${owner}: ${coordinate} must be a string when provided`)
+  }
+  return value
+}
+
+/** Проверяет exact marker payload на selection boundary. / Validates an exact marker payload at a selection boundary. */
+export function validateSelectionMarker(
+  owner: string,
+  coordinate: string,
+  marker: SMarker | undefined,
+): SMarker | undefined {
+  if (marker === undefined) return undefined
+  assertRecord(owner, coordinate, marker)
+  const tone = marker.tone
+  if (typeof tone !== 'string' || !MARKER_TONES.some((candidate) => candidate === tone)) {
+    throw new TypeError(`${owner}: ${coordinate}.tone is not a supported marker tone`)
+  }
+  const expectedKeys = tone === 'custom' ? new Set(['tone', 'color']) : new Set(['tone'])
+  assertExactKeys(owner, coordinate, marker, expectedKeys)
+  if (tone === 'custom') createCustomMarker(validateNonEmptyString(owner, `${coordinate}.color`, marker.color))
+  return marker
+}
+
+function resolveOption<TKey extends SelectionKey>(
+  owner: string,
+  value: SelectionOption<TKey>,
+  coordinate: string,
+): ResolvedSelectionOption<TKey> {
+  assertRecord(owner, coordinate, value)
+  assertExactKeys(owner, coordinate, value, OPTION_KEYS)
+  const key = value.value
+  const token = selectionKeyToken(owner, key, `${coordinate}.value`)
+  const label = validateNonEmptyString(owner, `${coordinate}.label`, value.label)
+  const title = validateOptionalSelectionString(owner, `${coordinate}.title`, value.title)
+  if (value.disabled !== undefined) validateBoolean(owner, `${coordinate}.disabled`, value.disabled)
+  const marker = validateSelectionMarker(owner, `${coordinate}.marker`, value.marker)
+  const option: SelectionOption<TKey> = {
+    value: key,
+    label,
+    ...(title === undefined ? {} : { title }),
+    ...(marker === undefined ? {} : { marker }),
+    ...(value.disabled === undefined ? {} : { disabled: value.disabled }),
+  }
+  return {
+    option,
+    token,
+    coordinate,
+  }
+}
+
+/**
+ * Проверяет весь inventory и возвращает новый типизированный контейнер без непроверенных полей.
+ * Validates the complete inventory and returns a new typed container without unchecked fields.
+ */
+export function resolveSelectionInventory<TKey extends SelectionKey>(
+  owner: string,
+  value: readonly SelectionEntry<TKey>[],
+): ResolvedSelectionInventory<TKey> {
+  if (!Array.isArray(value)) throw new TypeError(`${owner}: options must be an array`)
+  const typedEntries: readonly SelectionEntry<TKey>[] = value
+  const entries: ResolvedSelectionEntry<TKey>[] = []
+  const options: ResolvedSelectionOption<TKey>[] = []
+  const optionIdentities: Array<{ key: TKey; coordinate: string }> = []
+  const groupIdentities: Array<{ key: string; coordinate: string }> = []
+
+  for (const [entryIndex, entryValue] of typedEntries.entries()) {
+    const coordinate = `options[${entryIndex}]`
+    assertRecord(owner, coordinate, entryValue)
+    if ('groupId' in entryValue) {
+      assertExactKeys(owner, coordinate, entryValue, GROUP_KEYS)
+      const groupId = validateNonEmptyString(owner, `${coordinate}.groupId`, entryValue.groupId)
+      const label = validateNonEmptyString(owner, `${coordinate}.label`, entryValue.label)
+      if (!Array.isArray(entryValue.options)) {
+        throw new TypeError(`${owner}: ${coordinate}.options must be an array`)
+      }
+      if (entryValue.options.length === 0) {
+        throw new Error(`${owner}: ${coordinate}.options must contain at least one option`)
+      }
+      groupIdentities.push({ key: groupId, coordinate: `${coordinate}.groupId` })
+      const records = entryValue.options.map((option, optionIndex) => {
+        const optionCoordinate = `${coordinate}.options[${optionIndex}]`
+        const record = resolveOption<TKey>(owner, option, optionCoordinate)
+        optionIdentities.push({ key: record.option.value, coordinate: `${optionCoordinate}.value` })
+        options.push(record)
+        return record
+      })
+      entries.push({
+        kind: 'group',
+        groupId,
+        label,
+        records,
+        token: `group:${selectionKeyToken(owner, groupId, `${coordinate}.groupId`)}`,
+      })
+      continue
+    }
+
+    const record = resolveOption<TKey>(owner, entryValue, coordinate)
+    optionIdentities.push({ key: record.option.value, coordinate: `${coordinate}.value` })
+    options.push(record)
+    entries.push({ kind: 'option', record, token: `option:${record.token}` })
+  }
+
+  validateSelectionIdentities(`${owner} groups`, groupIdentities)
+  validateSelectionIdentities(owner, optionIdentities)
+  return {
+    entries,
+    options,
+    optionsByToken: new Map(options.map((record) => [record.token, record])),
+  }
+}
+
+/** Проверяет controlled model относительно точного inventory. / Validates the controlled model against the exact inventory. */
+export function validateSelectionModel<TKey extends SelectionKey>(
+  owner: string,
+  mode: SelectionMode,
+  modelValue: TKey | null | readonly TKey[] | undefined,
+  inventory: ResolvedSelectionInventory<TKey>,
+): ReadonlySet<string> {
+  if (modelValue === undefined) throw new TypeError(`${owner}: modelValue is required and cannot be undefined`)
+  if (mode === 'multiple') {
+    if (!Array.isArray(modelValue)) {
+      throw new TypeError(`${owner}: multiple selection requires modelValue to be an array`)
+    }
+    const tokens = validateSelectionIdentities(`${owner} modelValue`, modelValue.map((key, index) => ({
+      key,
+      coordinate: `modelValue[${index}]`,
+    })))
+    for (const token of tokens.keys()) {
+      if (!inventory.optionsByToken.has(token)) {
+        throw new Error(`${owner}: modelValue does not match every option`)
+      }
+    }
+    return new Set(tokens.keys())
+  }
+  if (isSelectionModelList(modelValue)) {
+    throw new TypeError(`${owner}: single selection requires modelValue to be a selection key or null`)
+  }
+  if (modelValue === null) return new Set()
+  const token = selectionKeyToken(owner, modelValue, 'modelValue')
+  if (!inventory.optionsByToken.has(token)) {
+    throw new Error(`${owner}: modelValue does not match any option`)
+  }
+  return new Set([token])
+}
+
+/** Narrowing helper for the exact multiple-selection model branch. */
+export function isSelectionModelList<TKey extends SelectionKey>(
+  value: TKey | null | readonly TKey[],
+): value is readonly TKey[] {
+  return Array.isArray(value)
+}

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

@@ -0,0 +1,31 @@
+import type { ComputedRef, InjectionKey } from 'vue';
+
+import type { SectionState, SidebarSectionsState } from '../containers/sidebar';
+
+/** Stable mounted descriptor registered by one SSidebarSection. */
+export interface SidebarSectionRegistration {
+  readonly key: string;
+  readonly element: HTMLElement;
+}
+
+/** DOM-ordered registered section with its exact controlled state. */
+export interface RegisteredSidebarSection {
+  readonly key: string;
+  readonly element: HTMLElement;
+  readonly state: Readonly<SectionState>;
+}
+
+export type SidebarSectionStyle = Readonly<Record<string, string | number>>;
+
+export interface SidebarGroupContext {
+  readonly sectionsState: ComputedRef<SidebarSectionsState>;
+  readonly orderedSections: ComputedRef<readonly RegisteredSidebarSection[]>;
+  registerSection(registration: SidebarSectionRegistration): () => void;
+  toggleSection(key: string): void;
+  getSectionStyle(key: string): SidebarSectionStyle;
+  beginResize(topKey: string, bottomKey: string): void;
+  resizeSections(topKey: string, bottomKey: string, requestedTopSize: number): void;
+  finishResize(topKey: string, bottomKey: string): void;
+}
+
+export const sidebarGroupContextKey: InjectionKey<SidebarGroupContext> = Symbol('SidebarGroupContext');

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

@@ -0,0 +1,57 @@
+import type { ComputedRef, InjectionKey } from 'vue'
+
+export type STabsActivationMode = 'automatic' | 'manual'
+export type STabRegistrationKey = string
+export type STabPanelRegistrationKey = string
+export type STabListRegistrationKey = symbol
+export type STabPanelsRegistrationKey = symbol
+
+export interface STabRegistration {
+  readonly tabKey: string
+  readonly disabled: () => boolean
+  readonly element: () => HTMLElement | null
+}
+
+export interface STabPanelRegistration {
+  readonly tabKey: string
+  readonly element: () => HTMLElement | null
+}
+
+export interface STabState {
+  readonly active: boolean
+  readonly disabled: boolean
+  readonly tabIndex: 0 | -1
+  readonly tabId: string
+  readonly panelId: string | undefined
+}
+
+export interface STabPanelState {
+  readonly active: boolean
+  readonly panelId: string
+  readonly tabId: string | undefined
+}
+
+export interface STabsContext {
+  readonly activeKey: ComputedRef<string | null>
+  readonly activationMode: ComputedRef<STabsActivationMode>
+  readonly closeButtonMode: ComputedRef<'reserve' | 'overlay'>
+  readonly tabDensity: ComputedRef<'compact' | 'default' | 'comfortable'>
+  readonly registerTab: (registration: STabRegistration) => STabRegistrationKey
+  readonly unregisterTab: (key: STabRegistrationKey) => void
+  readonly notifyTabOrderChanged: () => void
+  readonly getTabState: (key: STabRegistrationKey) => STabState
+  readonly getActiveTabElement: () => HTMLElement | null
+  readonly activateTab: (key: STabRegistrationKey) => void
+  readonly focusTab: (key: STabRegistrationKey) => void
+  readonly registerPanel: (registration: STabPanelRegistration) => STabPanelRegistrationKey
+  readonly unregisterPanel: (key: STabPanelRegistrationKey) => void
+  readonly notifyPanelOrderChanged: () => void
+  readonly getPanelState: (key: STabPanelRegistrationKey) => STabPanelState
+  readonly handleTabKeydown: (key: STabRegistrationKey, event: KeyboardEvent) => void
+  readonly registerTabList: (scrollActiveIntoCenter: () => void) => STabListRegistrationKey
+  readonly unregisterTabList: (key: STabListRegistrationKey) => void
+  readonly registerPanels: () => STabPanelsRegistrationKey
+  readonly unregisterPanels: (key: STabPanelsRegistrationKey) => void
+}
+
+export const tabsContextKey: InjectionKey<STabsContext> = Symbol('STabsContext')