@pgcorp/ui-kit 0.1.0

package/src/composables/useClipboard.ts

@@ -0,0 +1,37 @@
+export type ClipboardCopyResult =
+  | { status: 'copied'; method: 'clipboard-api' }
+  | { status: 'empty' }
+  | { status: 'unavailable'; reason: 'clipboard-api-missing' }
+  | { status: 'failed'; error: Error | DOMException }
+
+export interface ClipboardService {
+  copyText: (value: string) => Promise<ClipboardCopyResult>
+}
+
+/**
+ * Предоставляет единый типизированный контракт копирования текста.
+ * Provides the canonical typed text-copying contract.
+ */
+export function useClipboard(): ClipboardService {
+  const copyText = async (value: string): Promise<ClipboardCopyResult> => {
+    if (!value) return { status: 'empty' }
+
+    const clipboard = typeof navigator === 'undefined' ? undefined : navigator.clipboard
+    if (!clipboard?.writeText) {
+      return { status: 'unavailable', reason: 'clipboard-api-missing' }
+    }
+
+    try {
+      await clipboard.writeText(value)
+      return { status: 'copied', method: 'clipboard-api' }
+    } catch (cause) {
+      const isDomException = typeof DOMException !== 'undefined' && cause instanceof DOMException
+      const error = cause instanceof Error || isDomException
+        ? cause
+        : new Error('Clipboard API rejected writeText without an Error object', { cause })
+      return { status: 'failed', error }
+    }
+  }
+
+  return { copyText }
+}

package/src/composables/useDialogOverlay.ts

@@ -0,0 +1,85 @@
+import {
+  nextTick,
+  onBeforeUnmount,
+  ref,
+  watch,
+  type ComponentPublicInstance,
+  type Ref,
+} from 'vue'
+import { trapFocusInsidePanel } from '../components/shared/_internal/focusTrap'
+import { registerLayer, type LayerRegistration } from '../internal/layerStack'
+
+export interface DialogOverlayOptions {
+  open: Readonly<Ref<boolean>>
+  closable: Readonly<Ref<boolean>>
+  requestClose: () => void
+}
+
+export interface DialogOverlayController {
+  panelRef: Ref<HTMLElement | null>
+  setPanelElement: (element: Element | ComponentPublicInstance | null) => void
+  backdropStyle: Readonly<Ref<Record<string, string>>>
+  surfaceStyle: Readonly<Ref<Record<string, string>>>
+}
+
+/**
+ * Владеет modal-регистрацией, focus trap, body lock и восстановлением фокуса.
+ * Owns modal registration, focus trapping, body lock, and focus restoration.
+ */
+export function useDialogOverlay(options: DialogOverlayOptions): DialogOverlayController {
+  const panelRef = ref<HTMLElement | null>(null)
+  const backdropStyle = ref<Record<string, string>>({})
+  const surfaceStyle = ref<Record<string, string>>({})
+  let registration: LayerRegistration | null = null
+
+  const setPanelElement = (element: Element | ComponentPublicInstance | null): void => {
+    if (element === null || element instanceof HTMLElement) {
+      panelRef.value = element
+      return
+    }
+    throw new TypeError('Dialog overlay panel ref обязан указывать на HTMLElement')
+  }
+
+  const registerOpen = (): void => {
+    if (registration) return
+    const restoreTarget = typeof document !== 'undefined' && document.activeElement instanceof HTMLElement
+      ? document.activeElement
+      : null
+    registration = registerLayer({
+      kind: 'dialog',
+      root: () => panelRef.value,
+      modal: true,
+      restoreTarget,
+      dismissOnEscape: () => options.closable.value,
+      dismissOnOutsidePointer: () => options.closable.value,
+      trapFocus: (event) => trapFocusInsidePanel(event, panelRef, true),
+      requestDismiss: () => options.requestClose(),
+    })
+    backdropStyle.value = { zIndex: registration.zIndex }
+    surfaceStyle.value = {
+      zIndex: `calc(${registration.zIndex} + var(--s-layer-overlay-surface-offset))`,
+    }
+  }
+
+  const unregisterOpen = (restoreFocus = true): void => {
+    registration?.unregister({ restoreFocus })
+    registration = null
+    backdropStyle.value = {}
+    surfaceStyle.value = {}
+  }
+
+  watch(options.open, async (open, wasOpen) => {
+    if (open) {
+      registerOpen()
+      await nextTick()
+      if (options.open.value) panelRef.value?.focus()
+      return
+    }
+
+    unregisterOpen(Boolean(wasOpen))
+  }, { immediate: true })
+
+  onBeforeUnmount(() => unregisterOpen(false))
+
+  return { panelRef, setPanelElement, backdropStyle, surfaceStyle }
+}

package/src/composables/useDisclosure.ts

@@ -0,0 +1,40 @@
+import { computed, ref, toValue, useId, type MaybeRefOrGetter, type Ref } from 'vue'
+
+export interface UseDisclosureOptions {
+  id?: string
+  open?: Readonly<Ref<boolean>>
+  defaultOpen?: boolean
+  disabled?: MaybeRefOrGetter<boolean>
+  onUpdate?: (open: boolean) => void
+}
+
+/** Canonical controlled/uncontrolled state and ID contract for button disclosures. */
+export function useDisclosure(options: UseDisclosureOptions = {}) {
+  if (options.id !== undefined && options.id.trim().length === 0) {
+    throw new Error('useDisclosure: id must be a non-empty string')
+  }
+  if (options.open && !options.onUpdate) {
+    throw new Error('useDisclosure: controlled open requires onUpdate')
+  }
+  if (options.open && options.defaultOpen !== undefined) {
+    throw new Error('useDisclosure: controlled open cannot be combined with defaultOpen')
+  }
+
+  const generatedId = useId()
+  const baseId = options.id ?? `s-disclosure-${generatedId}`
+  const internalOpen = ref(options.defaultOpen ?? false)
+  const isControlled = options.open !== undefined
+  const isDisabled = computed(() => toValue(options.disabled ?? false))
+  const isOpen = computed(() => isControlled ? options.open!.value : internalOpen.value)
+  const triggerId = computed(() => `${baseId}-trigger`)
+  const panelId = computed(() => `${baseId}-panel`)
+
+  const setOpen = (nextOpen: boolean): void => {
+    if (isDisabled.value || nextOpen === isOpen.value) return
+    if (isControlled) options.onUpdate!(nextOpen)
+    else internalOpen.value = nextOpen
+  }
+  const toggle = (): void => setOpen(!isOpen.value)
+
+  return { isOpen, isDisabled, triggerId, panelId, setOpen, toggle }
+}

package/src/composables/useFloatingPosition.ts

@@ -0,0 +1,245 @@
+import { nextTick, onBeforeUnmount, onMounted, ref, watch, type Ref } from 'vue'
+
+export type FloatingSide = 'top' | 'bottom' | 'left' | 'right'
+export type FloatingAlignment = 'start' | 'center' | 'end'
+export type FloatingPlacement = `${FloatingSide}-${FloatingAlignment}`
+export type FloatingWidthMatch = 'none' | 'min' | 'exact'
+
+export interface FloatingPositionOptions {
+  active: Readonly<Ref<boolean>>
+  placement: () => FloatingPlacement
+  anchorElement?: () => HTMLElement | null
+  anchorRect?: () => DOMRect | null
+  panelRef?: Ref<HTMLElement | null>
+  offset?: () => number
+  boundaryPadding?: () => number
+  flip?: () => boolean
+  shift?: () => boolean
+  widthMatch?: () => FloatingWidthMatch
+  zIndex?: () => string
+  scrollStrategy?: 'reposition' | 'close'
+  requestClose?: () => void
+}
+
+export interface FloatingPositionController {
+  anchorRef: Ref<HTMLElement | null>
+  panelRef: Ref<HTMLElement | null>
+  floatingStyle: Ref<Record<string, string>>
+  arrowStyle: Ref<Record<string, string>>
+  resolvedPlacement: Ref<FloatingPlacement>
+  coordinates: Ref<FloatingCoordinates>
+  updatePosition: () => void
+}
+
+/** Координаты floating-поверхности во viewport. / Floating-surface viewport coordinates. */
+export interface FloatingCoordinates {
+  left: number
+  top: number
+}
+
+const oppositeSide: Record<FloatingSide, FloatingSide> = {
+  top: 'bottom',
+  bottom: 'top',
+  left: 'right',
+  right: 'left',
+}
+
+function splitPlacement(placement: FloatingPlacement): [FloatingSide, FloatingAlignment] {
+  return placement.split('-') as [FloatingSide, FloatingAlignment]
+}
+
+function alignedOffset(start: number, anchorSize: number, panelSize: number, alignment: FloatingAlignment): number {
+  if (alignment === 'start') return start
+  if (alignment === 'end') return start + anchorSize - panelSize
+  return start + (anchorSize - panelSize) / 2
+}
+
+function coordinatesFor(
+  side: FloatingSide,
+  alignment: FloatingAlignment,
+  anchor: DOMRect,
+  panelWidth: number,
+  panelHeight: number,
+  offset: number,
+): FloatingCoordinates {
+  if (side === 'top' || side === 'bottom') {
+    return {
+      left: alignedOffset(anchor.left, anchor.width, panelWidth, alignment),
+      top: side === 'top' ? anchor.top - panelHeight - offset : anchor.bottom + offset,
+    }
+  }
+  return {
+    left: side === 'left' ? anchor.left - panelWidth - offset : anchor.right + offset,
+    top: alignedOffset(anchor.top, anchor.height, panelHeight, alignment),
+  }
+}
+
+function mainAxisOverflow(
+  side: FloatingSide,
+  coordinates: FloatingCoordinates,
+  panelWidth: number,
+  panelHeight: number,
+  viewportWidth: number,
+  viewportHeight: number,
+  padding: number,
+): number {
+  if (side === 'top') return Math.max(0, padding - coordinates.top)
+  if (side === 'bottom') return Math.max(0, coordinates.top + panelHeight - (viewportHeight - padding))
+  if (side === 'left') return Math.max(0, padding - coordinates.left)
+  return Math.max(0, coordinates.left + panelWidth - (viewportWidth - padding))
+}
+
+function clampArrowCoordinate(coordinate: number, panelSize: number): number {
+  const inset = Math.min(10, panelSize / 2)
+  return Math.max(inset, Math.min(coordinate, panelSize - inset))
+}
+
+/**
+ * Единый владелец geometry/collision/observer-контракта floating surfaces.
+ * Canonical owner of floating-surface geometry, collision and observers.
+ */
+export function useFloatingPosition(options: FloatingPositionOptions): FloatingPositionController {
+  const anchorRef = ref<HTMLElement | null>(null)
+  const panelRef = options.panelRef ?? ref<HTMLElement | null>(null)
+  const floatingStyle = ref<Record<string, string>>({})
+  const arrowStyle = ref<Record<string, string>>({})
+  const resolvedPlacement = ref<FloatingPlacement>(options.placement())
+  const resolvedCoordinates = ref<FloatingCoordinates>({ left: -10000, top: -10000 })
+  let resizeObserver: ResizeObserver | null = null
+  let listenersAttached = false
+
+  const updatePosition = (): void => {
+    if (!options.active.value || typeof window === 'undefined') return
+    const anchorElement = options.anchorElement?.() ?? anchorRef.value
+    const panelElement = panelRef.value
+    const anchor = options.anchorRect?.() ?? anchorElement?.getBoundingClientRect() ?? null
+    if (!anchor || !panelElement) return
+
+    const panel = panelElement.getBoundingClientRect()
+    const panelWidth = panel.width || panelElement.offsetWidth
+    const panelHeight = panel.height || panelElement.offsetHeight
+    const offset = options.offset?.() ?? 6
+    const padding = options.boundaryPadding?.() ?? 8
+    const viewportWidth = window.innerWidth
+    const viewportHeight = window.innerHeight
+    const [preferredSide, alignment] = splitPlacement(options.placement())
+    let side = preferredSide
+    let coordinates = coordinatesFor(side, alignment, anchor, panelWidth, panelHeight, offset)
+
+    if (options.flip?.() ?? true) {
+      const alternateSide = oppositeSide[side]
+      const alternateCoordinates = coordinatesFor(alternateSide, alignment, anchor, panelWidth, panelHeight, offset)
+      const preferredOverflow = mainAxisOverflow(
+        side, coordinates, panelWidth, panelHeight, viewportWidth, viewportHeight, padding,
+      )
+      const alternateOverflow = mainAxisOverflow(
+        alternateSide, alternateCoordinates, panelWidth, panelHeight, viewportWidth, viewportHeight, padding,
+      )
+      if (alternateOverflow < preferredOverflow) {
+        side = alternateSide
+        coordinates = alternateCoordinates
+      }
+    }
+
+    if (options.shift?.() ?? true) {
+      coordinates.left = Math.max(padding, Math.min(coordinates.left, viewportWidth - panelWidth - padding))
+      coordinates.top = Math.max(padding, Math.min(coordinates.top, viewportHeight - panelHeight - padding))
+    }
+
+    const placement = `${side}-${alignment}` as FloatingPlacement
+    resolvedPlacement.value = placement
+    resolvedCoordinates.value = {
+      left: Math.round(coordinates.left),
+      top: Math.round(coordinates.top),
+    }
+    const widthMatch = options.widthMatch?.() ?? 'none'
+    floatingStyle.value = {
+      position: 'fixed',
+      left: `${resolvedCoordinates.value.left}px`,
+      top: `${resolvedCoordinates.value.top}px`,
+      zIndex: options.zIndex?.() ?? 'var(--s-layer-floating)',
+      ...(widthMatch === 'min' ? { minWidth: `${Math.round(anchor.width)}px` } : {}),
+      ...(widthMatch === 'exact' ? { width: `${Math.round(anchor.width)}px` } : {}),
+    }
+
+    if (side === 'top' || side === 'bottom') {
+      const anchorCenter = anchor.left + anchor.width / 2 - coordinates.left
+      arrowStyle.value = {
+        left: `${Math.round(clampArrowCoordinate(anchorCenter, panelWidth))}px`,
+      }
+    } else {
+      const anchorCenter = anchor.top + anchor.height / 2 - coordinates.top
+      arrowStyle.value = {
+        top: `${Math.round(clampArrowCoordinate(anchorCenter, panelHeight))}px`,
+      }
+    }
+  }
+
+  const handleScroll = (): void => {
+    if (!options.active.value) return
+    if (options.scrollStrategy === 'close') {
+      options.requestClose?.()
+      return
+    }
+    updatePosition()
+  }
+
+  const attachListeners = (): void => {
+    if (listenersAttached || typeof window === 'undefined') return
+    listenersAttached = true
+    window.addEventListener('resize', updatePosition, { passive: true })
+    window.addEventListener('scroll', handleScroll, { passive: true, capture: true })
+    if (typeof ResizeObserver !== 'undefined') {
+      resizeObserver = new ResizeObserver(updatePosition)
+      const observedAnchor = options.anchorElement?.() ?? anchorRef.value
+      if (observedAnchor) resizeObserver.observe(observedAnchor)
+      if (panelRef.value) resizeObserver.observe(panelRef.value)
+    }
+  }
+
+  const detachListeners = (): void => {
+    if (!listenersAttached || typeof window === 'undefined') return
+    listenersAttached = false
+    window.removeEventListener('resize', updatePosition)
+    window.removeEventListener('scroll', handleScroll, true)
+    resizeObserver?.disconnect()
+    resizeObserver = null
+  }
+
+  watch(options.active, async (active) => {
+    if (!active) {
+      detachListeners()
+      floatingStyle.value = {}
+      arrowStyle.value = {}
+      resolvedCoordinates.value = { left: -10000, top: -10000 }
+      return
+    }
+    floatingStyle.value = {
+      position: 'fixed',
+      left: '-10000px',
+      top: '-10000px',
+      zIndex: options.zIndex?.() ?? 'var(--s-layer-floating)',
+    }
+    await nextTick()
+    attachListeners()
+    updatePosition()
+  }, { immediate: true })
+
+  onMounted(() => {
+    if (options.active.value) {
+      attachListeners()
+      updatePosition()
+    }
+  })
+  onBeforeUnmount(detachListeners)
+
+  return {
+    anchorRef,
+    panelRef,
+    floatingStyle,
+    arrowStyle,
+    resolvedPlacement,
+    coordinates: resolvedCoordinates,
+    updatePosition,
+  }
+}

package/src/composables/useNotifier.ts

@@ -0,0 +1,26 @@
+import { useNotifierStore } from '../stores/useNotifierStore'
+import type { NotificationInput, Severity } from '../stores/useNotifierStore'
+
+export type NotifyOptions = Pick<NotificationInput, 'title' | 'message' | 'duration'>
+
+type NotifyArg = NotifyOptions | string
+
+// This composable provides a clean API to trigger notifications from any component.
+export function useNotifier() {
+  const store = useNotifierStore()
+
+  const notify = (severity: Severity, options: NotifyArg) => {
+    const payload: NotifyOptions = typeof options === 'string' ? { message: options } : options
+    store.add({
+      severity,
+      ...payload,
+    })
+  }
+
+  return {
+    info: (options: NotifyArg) => notify('info', options),
+    success: (options: NotifyArg) => notify('success', options),
+    warn: (options: NotifyArg) => notify('warn', options),
+    danger: (options: NotifyArg) => notify('danger', options),
+  }
+}