@pgcorp/ui-kit 0.1.0

package/src/internal/layerStack.ts

@@ -0,0 +1,202 @@
+import { isFocusableElement } from './focusNavigation'
+
+export type LayerKind = 'dialog' | 'listbox' | 'menu' | 'popover' | 'tooltip'
+export type LayerDismissReason = 'escape' | 'outside-contextmenu' | 'outside-pointer'
+
+export interface LayerRegistrationOptions {
+  kind: LayerKind
+  root: () => HTMLElement | null
+  anchor?: () => HTMLElement | null
+  branches?: () => readonly HTMLElement[]
+  modal?: boolean
+  restoreTarget?: HTMLElement | null
+  dismissOnEscape?: () => boolean
+  dismissOnOutsidePointer?: () => boolean
+  blocksParentFocusTrap?: boolean
+  trapFocus?: (event: KeyboardEvent) => void
+  requestDismiss: (reason: LayerDismissReason, event: Event) => void
+}
+
+export interface LayerRegistration {
+  readonly id: symbol
+  readonly zIndex: string
+  readonly focusScope: () => ParentNode
+  unregister: (options?: { restoreFocus?: boolean }) => void
+}
+
+interface LayerEntry extends LayerRegistrationOptions {
+  id: symbol
+  parentId: symbol | null
+  restoreTarget: HTMLElement | null
+  tier: 'floating' | 'overlay'
+  zIndex: string
+}
+
+const layers: LayerEntry[] = []
+let listenersAttached = false
+let bodyLockCount = 0
+let preservedBodyOverflow = ''
+
+const entryContains = (entry: LayerEntry, target: Node): boolean => {
+  if (entry.root()?.contains(target) || entry.anchor?.()?.contains(target)) return true
+  return entry.branches?.().some((branch) => branch.contains(target)) ?? false
+}
+
+const findParentId = (options: LayerRegistrationOptions): symbol | null => {
+  const reference = options.anchor?.()
+    ?? options.restoreTarget
+    ?? (typeof document !== 'undefined' && document.activeElement instanceof HTMLElement
+      ? document.activeElement
+      : null)
+  if (!reference) return null
+  return [...layers].reverse().find((entry) => entryContains(entry, reference))?.id ?? null
+}
+
+const topmostLayer = (): LayerEntry | undefined => layers[layers.length - 1]
+
+const resolveFocusScope = (entry: LayerEntry): ParentNode => {
+  let parentId = entry.parentId
+  while (parentId) {
+    const parent = layers.find((candidate) => candidate.id === parentId)
+    if (!parent) break
+    if (parent.modal || parent.trapFocus) {
+      return parent.root() ?? document
+    }
+    parentId = parent.parentId
+  }
+  return document
+}
+
+const handleGlobalKeydown = (event: KeyboardEvent): void => {
+  const topmost = topmostLayer()
+  if (!topmost) return
+
+  if (event.key === 'Escape') {
+    if (topmost.dismissOnEscape?.() ?? true) {
+      event.preventDefault()
+      event.stopPropagation()
+      topmost.requestDismiss('escape', event)
+    }
+    return
+  }
+
+  if (event.key !== 'Tab') return
+  let trapIndex = -1
+  for (let index = layers.length - 1; index >= 0; index -= 1) {
+    if (layers[index]?.trapFocus) {
+      trapIndex = index
+      break
+    }
+  }
+  if (trapIndex < 0) return
+  const blockedByChild = layers
+    .slice(trapIndex + 1)
+    .some((entry) => entry.blocksParentFocusTrap ?? true)
+  if (!blockedByChild) layers[trapIndex]?.trapFocus?.(event)
+}
+
+const handleGlobalOutsideEvent = (event: Event, reason: LayerDismissReason): void => {
+  const topmost = topmostLayer()
+  if (!topmost) return
+  const target = event.target
+  if (target instanceof Node && entryContains(topmost, target)) return
+  if (topmost.dismissOnOutsidePointer?.() ?? true) topmost.requestDismiss(reason, event)
+}
+
+const handleGlobalPointerDown = (event: PointerEvent): void => {
+  handleGlobalOutsideEvent(event, 'outside-pointer')
+}
+
+const handleGlobalContextMenu = (event: MouseEvent): void => {
+  handleGlobalOutsideEvent(event, 'outside-contextmenu')
+}
+
+const attachListeners = (): void => {
+  if (listenersAttached || typeof window === 'undefined' || typeof document === 'undefined') return
+  listenersAttached = true
+  window.addEventListener('keydown', handleGlobalKeydown, true)
+  document.addEventListener('pointerdown', handleGlobalPointerDown, true)
+  document.addEventListener('contextmenu', handleGlobalContextMenu, true)
+}
+
+const detachListeners = (): void => {
+  if (!listenersAttached || layers.length > 0 || typeof window === 'undefined' || typeof document === 'undefined') return
+  listenersAttached = false
+  window.removeEventListener('keydown', handleGlobalKeydown, true)
+  document.removeEventListener('pointerdown', handleGlobalPointerDown, true)
+  document.removeEventListener('contextmenu', handleGlobalContextMenu, true)
+}
+
+const lockBody = (): void => {
+  if (typeof document === 'undefined') return
+  if (bodyLockCount === 0) {
+    preservedBodyOverflow = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+  }
+  bodyLockCount += 1
+}
+
+const unlockBody = (): void => {
+  if (typeof document === 'undefined') return
+  bodyLockCount = Math.max(0, bodyLockCount - 1)
+  if (bodyLockCount === 0) document.body.style.overflow = preservedBodyOverflow
+}
+
+const scheduleFocusRestore = (entry: LayerEntry): void => {
+  queueMicrotask(() => {
+    if (entry.restoreTarget?.isConnected && isFocusableElement(entry.restoreTarget)) {
+      entry.restoreTarget.focus()
+      return
+    }
+    topmostLayer()?.root()?.focus()
+  })
+}
+
+/**
+ * Регистрирует одну открытую overlay-поверхность в общем dismiss/focus/body-lock стеке.
+ * Registers one open overlay surface in the shared dismiss/focus/body-lock stack.
+ */
+export function registerLayer(options: LayerRegistrationOptions): LayerRegistration {
+  const previousTopmost = topmostLayer()
+  const tier = options.modal || previousTopmost?.tier === 'overlay' ? 'overlay' : 'floating'
+  const zIndex = previousTopmost && previousTopmost.tier === tier
+    ? `calc(${previousTopmost.zIndex} + var(--s-layer-overlay-step))`
+    : tier === 'overlay'
+      ? 'var(--s-layer-overlay-backdrop)'
+      : 'var(--s-layer-floating)'
+  const entry: LayerEntry = {
+    ...options,
+    id: Symbol(options.kind),
+    parentId: findParentId(options),
+    restoreTarget: options.restoreTarget ?? null,
+    tier,
+    zIndex,
+  }
+  let registered = true
+  layers.push(entry)
+  if (entry.modal) lockBody()
+  attachListeners()
+
+  return {
+    id: entry.id,
+    zIndex: entry.zIndex,
+    focusScope: () => resolveFocusScope(entry),
+    unregister: ({ restoreFocus = false } = {}) => {
+      if (!registered) return
+      registered = false
+      const index = layers.findIndex((candidate) => candidate.id === entry.id)
+      const wasTopmost = index === layers.length - 1
+      if (index >= 0) {
+        const removedRoot = entry.root()
+        for (const layer of layers.slice(index + 1)) {
+          if (layer.parentId === entry.id) layer.parentId = entry.parentId
+          if (removedRoot?.contains(layer.restoreTarget)) layer.restoreTarget = entry.restoreTarget
+        }
+        layers.splice(index, 1)
+      }
+      if (entry.modal) unlockBody()
+      detachListeners()
+      if (restoreFocus && wasTopmost) scheduleFocusRestore(entry)
+    },
+  }
+}

package/src/internal/linkTarget.ts

@@ -0,0 +1,256 @@
+import {
+  LINK_BROWSING_TARGETS,
+  type LinkBrowsingTarget,
+  type LinkHistoryStateValue,
+  type LinkRouteScalar,
+  type LinkRouterTarget,
+} from '../components/shared/controls/SLink'
+
+/** Runtime input accepts unknown fields so every public owner validates the actual payload. */
+export interface LinkTargetInput {
+  readonly href?: unknown
+  readonly to?: unknown
+  readonly target?: unknown
+  readonly rel?: unknown
+  readonly owner: string
+}
+
+export type ResolvedLinkTarget =
+  | { readonly kind: 'anchor'; readonly bindings: { readonly href: string; readonly target: LinkBrowsingTarget; readonly rel?: string } }
+  | { readonly kind: 'router'; readonly bindings: { readonly to: LinkRouterTarget; readonly target: LinkBrowsingTarget; readonly rel?: string } }
+
+const ROUTE_KEYS = new Set(['name', 'path', 'params', 'query', 'hash', 'replace', 'force', 'state'])
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+function hasOwn(value: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key)
+}
+
+function isRouteScalar(value: unknown): value is LinkRouteScalar {
+  return value === null
+    || value === undefined
+    || typeof value === 'string'
+    || (typeof value === 'number' && Number.isFinite(value))
+}
+
+function enumerableDataEntries(
+  owner: string,
+  coordinate: string,
+  value: Record<string, unknown>,
+): Array<readonly [string, unknown]> {
+  const entries: Array<readonly [string, unknown]> = []
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== 'string') {
+      throw new TypeError(`${owner}: ${coordinate} не допускает symbol keys / ${coordinate} does not allow symbol keys`)
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)
+    if (!descriptor?.enumerable || !('value' in descriptor)) {
+      throw new TypeError(
+        `${owner}: ${coordinate}.${key} должен быть enumerable data property `
+        + `/ ${coordinate}.${key} must be an enumerable data property`,
+      )
+    }
+    entries.push([key, descriptor.value])
+  }
+  return entries
+}
+
+function validateDenseScalarArray(
+  owner: string,
+  coordinate: string,
+  value: readonly unknown[],
+  allowNullish: boolean,
+): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index))
+    if (!descriptor?.enumerable || !('value' in descriptor)) return false
+    if (!isRouteScalar(descriptor.value)) return false
+    if (!allowNullish && (descriptor.value === null || descriptor.value === undefined)) return false
+  }
+  return Reflect.ownKeys(value).every((key) => key === 'length' || (
+    typeof key === 'string'
+    && /^(0|[1-9]\d*)$/u.test(key)
+    && Number(key) < value.length
+  ))
+}
+
+function validateRouteDictionary(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+  allowNullishArrayValues: boolean,
+): void {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${owner}: ${coordinate} должен быть plain object / ${coordinate} must be a plain object`)
+  }
+  for (const [key, candidate] of enumerableDataEntries(owner, coordinate, value)) {
+    const validArray = Array.isArray(candidate)
+      && validateDenseScalarArray(owner, `${coordinate}.${key}`, candidate, allowNullishArrayValues)
+    if (!isRouteScalar(candidate) && !validArray) {
+      throw new TypeError(
+        `${owner}: ${coordinate}.${key} должен быть scalar или массивом scalar `
+        + `/ ${coordinate}.${key} must be a scalar or scalar array`,
+      )
+    }
+  }
+}
+
+function validateHistoryStateValue(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+  ancestors: Set<object>,
+): asserts value is LinkHistoryStateValue {
+  if (value === null || value === undefined || ['string', 'number', 'boolean'].includes(typeof value)) return
+  if (typeof value !== 'object') {
+    throw new TypeError(`${owner}: ${coordinate} содержит неподдерживаемое state value / ${coordinate} contains an unsupported state value`)
+  }
+  if (ancestors.has(value)) {
+    throw new TypeError(`${owner}: ${coordinate} содержит cycle / ${coordinate} contains a cycle`)
+  }
+  if (!Array.isArray(value) && !isPlainObject(value)) {
+    throw new TypeError(`${owner}: ${coordinate} должен содержать только plain objects/arrays / ${coordinate} must contain only plain objects/arrays`)
+  }
+  ancestors.add(value)
+  if (Array.isArray(value)) {
+    if (!Reflect.ownKeys(value).every((key) => key === 'length' || (
+      typeof key === 'string'
+      && /^(0|[1-9]\d*)$/u.test(key)
+      && Number(key) < value.length
+    ))) {
+      throw new TypeError(`${owner}: ${coordinate} не должен быть sparse / ${coordinate} must not be sparse`)
+    }
+    for (let index = 0; index < value.length; index += 1) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, String(index))
+      if (!descriptor?.enumerable || !('value' in descriptor)) {
+        throw new TypeError(`${owner}: ${coordinate} не должен быть sparse/accessor / ${coordinate} must not be sparse/accessor`)
+      }
+      validateHistoryStateValue(owner, `${coordinate}[${index}]`, descriptor.value, ancestors)
+    }
+  } else {
+    for (const [key, item] of enumerableDataEntries(owner, coordinate, value)) {
+      validateHistoryStateValue(owner, `${coordinate}.${key}`, item, ancestors)
+    }
+  }
+  ancestors.delete(value)
+}
+
+function isRouterTarget(owner: string, value: unknown): value is LinkRouterTarget {
+  if (typeof value === 'string') {
+    if (value.trim().length > 0 && value === value.trim()) return true
+    throw new TypeError(
+      `${owner}: to должен быть непустой строкой или route object `
+      + '/ to must be a non-empty string or route object',
+    )
+  }
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${owner}: to должен быть plain route object / to must be a plain route object`)
+  }
+  const routeEntries = enumerableDataEntries(owner, 'to', value)
+  for (const [key] of routeEntries) {
+    if (!ROUTE_KEYS.has(key)) {
+      throw new TypeError(
+        `${owner}: to route object содержит неподдерживаемое поле ${JSON.stringify(key)} `
+        + `/ to route object contains unsupported field ${JSON.stringify(key)}`,
+      )
+    }
+  }
+  const hasName = hasOwn(value, 'name')
+  const hasPath = hasOwn(value, 'path')
+  if (hasName === hasPath) {
+    throw new TypeError(
+      `${owner}: to route object должен содержать ровно один explicit name/path `
+      + '/ to route object must contain exactly one explicit name/path',
+    )
+  }
+  if (hasName && !(
+    typeof value.name === 'symbol'
+    || (typeof value.name === 'string' && value.name.trim().length > 0)
+  )) {
+    throw new TypeError(`${owner}: to.name должен быть непустой строкой или symbol / to.name must be a non-empty string or symbol`)
+  }
+  if (hasPath && (typeof value.path !== 'string' || value.path.trim().length === 0)) {
+    throw new TypeError(`${owner}: to.path должен быть непустой строкой / to.path must be a non-empty string`)
+  }
+  if (hasPath && value.params !== undefined) {
+    throw new TypeError(`${owner}: to.params допустим только для named route / to.params is only supported for a named route`)
+  }
+  if (value.params !== undefined) validateRouteDictionary(owner, 'to.params', value.params, false)
+  if (value.query !== undefined) validateRouteDictionary(owner, 'to.query', value.query, true)
+  if (value.hash !== undefined && typeof value.hash !== 'string') {
+    throw new TypeError(`${owner}: to.hash должен быть строкой / to.hash must be a string`)
+  }
+  for (const key of ['replace', 'force'] as const) {
+    if (value[key] !== undefined && typeof value[key] !== 'boolean') {
+      throw new TypeError(`${owner}: to.${key} должен быть boolean / to.${key} must be a boolean`)
+    }
+  }
+  if (value.state !== undefined) {
+    if (!isPlainObject(value.state)) {
+      throw new TypeError(`${owner}: to.state должен быть plain object / to.state must be a plain object`)
+    }
+    validateHistoryStateValue(owner, 'to.state', value.state, new Set<object>())
+  }
+  return true
+}
+
+function isBrowsingTarget(value: unknown): value is LinkBrowsingTarget {
+  for (const target of LINK_BROWSING_TARGETS) {
+    if (value === target) return true
+  }
+  return false
+}
+
+function resolveBrowsingTarget(owner: string, value: unknown): LinkBrowsingTarget {
+  if (value === undefined) return '_self'
+  if (isBrowsingTarget(value)) return value
+  throw new TypeError(
+    `${owner}: target должен быть одним из ${LINK_BROWSING_TARGETS.join(', ')} `
+    + `/ target must be one of ${LINK_BROWSING_TARGETS.join(', ')}`,
+  )
+}
+
+function resolveRel(owner: string, value: unknown, target: LinkBrowsingTarget): string | undefined {
+  if (value === undefined) return target === '_blank' ? 'noopener noreferrer' : undefined
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new TypeError(`${owner}: rel должен быть непустой строкой / rel must be a non-empty string`)
+  }
+  if (target !== '_blank') return value
+
+  const tokens = value.trim().split(/\s+/u)
+  const comparableTokens = new Set(tokens.map((token) => token.toLowerCase()))
+  if (!comparableTokens.has('noopener')) tokens.push('noopener')
+  if (!comparableTokens.has('noreferrer')) tokens.push('noreferrer')
+  return tokens.join(' ')
+}
+
+/** Validates the sole link-target boundary and secures new browsing contexts. */
+export function resolveLinkTarget(input: LinkTargetInput): ResolvedLinkTarget {
+  const hasHref = input.href !== undefined
+  const hasTo = input.to !== undefined
+  if (hasHref === hasTo) {
+    throw new TypeError(`${input.owner}: передайте ровно один target — href или to`)
+  }
+
+  const target = resolveBrowsingTarget(input.owner, input.target)
+  const rel = resolveRel(input.owner, input.rel, target)
+  if (hasHref) {
+    if (
+      typeof input.href !== 'string'
+      || input.href.trim().length === 0
+      || input.href !== input.href.trim()
+    ) {
+      throw new TypeError(`${input.owner}: href должен быть непустой строкой / href must be a non-empty string`)
+    }
+    return { kind: 'anchor', bindings: { href: input.href, target, ...(rel === undefined ? {} : { rel }) } }
+  }
+  if (isRouterTarget(input.owner, input.to)) {
+    return { kind: 'router', bindings: { to: input.to, target, ...(rel === undefined ? {} : { rel }) } }
+  }
+  throw new TypeError(`${input.owner}: недостижимый router target / unreachable router target`)
+}