@pgcorp/ui-kit 0.9.0 → 0.10.1

package/src/internal/codeEditorContract.ts

@@ -1,110 +0,0 @@
-import {
-  validateBoolean,
-  validateBoundedInteger,
-  validateExactString,
-  validateNonEmptyString,
-} from './runtimeContract'
-
-export const CODE_EDITOR_VIEWPORTS = ['content', 'document', 'compact', 'standard', 'expanded', 'fill'] as const
-export const CODE_EDITOR_VARIANTS = ['code', 'sql'] as const
-export const CODE_EDITOR_KEY_BEHAVIORS = ['indent', 'focus-next'] as const
-export const CODE_EDITOR_CURSOR_ACTIVITY_MODES = ['editable', 'always'] as const
-
-/**
- * Язык задаётся явно либо определяется только из обязательного пути файла.
- * Language is either explicit or detected exclusively from a required file path.
- */
-export type CodeEditorLanguageContract =
-  | { mode: 'explicit'; id: string; filePath?: never }
-  | { mode: 'detect'; filePath: string; id?: never }
-
-/** Явные CodeMirror-возможности без вывода опций из presentation. / Explicit CodeMirror capabilities; no option is inferred from presentation. */
-export interface CodeEditorCapabilitiesContract {
-  lineNumbers: boolean
-  indentation: {
-    tabSize: number
-    keyBehavior: typeof CODE_EDITOR_KEY_BEHAVIORS[number]
-  }
-  keyInterceptor?: (event: KeyboardEvent) => boolean
-  cursorActivity: typeof CODE_EDITOR_CURSOR_ACTIVITY_MODES[number]
-}
-
-function isCodeEditorKeyInterceptor(value: unknown): value is (event: KeyboardEvent) => boolean {
-  return typeof value === 'function'
-}
-
-function assertPlainExactRecord(
-  owner: string,
-  coordinate: string,
-  value: unknown,
-  allowed: readonly string[],
-): Record<string, unknown> {
-  if (typeof value !== 'object' || value === null || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype) {
-    throw new TypeError(`${owner}: ${coordinate} должен быть plain object. / ${owner}: ${coordinate} must be a plain object.`)
-  }
-  const record = value as Record<string, unknown>
-  const unexpected = Object.keys(record).filter((key) => !allowed.includes(key))
-  if (unexpected.length > 0) {
-    throw new TypeError(`${owner}.${coordinate}: неизвестные поля ${unexpected.map((key) => JSON.stringify(key)).join(', ')}. / ${owner}.${coordinate}: unknown fields ${unexpected.map((key) => JSON.stringify(key)).join(', ')}.`)
-  }
-  return record
-}
-
-export function validateCodeEditorLanguage(
-  owner: string,
-  value: unknown,
-): CodeEditorLanguageContract {
-  const record = assertPlainExactRecord(owner, 'language', value, ['mode', 'id', 'filePath'])
-  const mode = validateExactString(owner, 'language.mode', record.mode, ['explicit', 'detect'] as const)
-  const allowedFields = mode === 'explicit' ? ['mode', 'id'] : ['mode', 'filePath']
-  const unexpected = Object.keys(record).filter((key) => !allowedFields.includes(key))
-  if (unexpected.length > 0) {
-    throw new TypeError(
-      `${owner}.language: неизвестные поля ${unexpected.map((key) => JSON.stringify(key)).join(', ')}. `
-      + `/ ${owner}.language: unknown fields ${unexpected.map((key) => JSON.stringify(key)).join(', ')}.`,
-    )
-  }
-  if (mode === 'explicit') {
-    return { mode, id: validateNonEmptyString(owner, 'language.id', record.id) }
-  }
-  return { mode, filePath: validateNonEmptyString(owner, 'language.filePath', record.filePath) }
-}
-
-export function validateCodeEditorCapabilities(
-  owner: string,
-  value: unknown,
-): CodeEditorCapabilitiesContract {
-  const record = assertPlainExactRecord(
-    owner,
-    'capabilities',
-    value,
-    ['lineNumbers', 'indentation', 'keyInterceptor', 'cursorActivity'],
-  )
-  const indentation = assertPlainExactRecord(
-    owner,
-    'capabilities.indentation',
-    record.indentation,
-    ['tabSize', 'keyBehavior'],
-  )
-  const keyInterceptor = record.keyInterceptor
-  if (keyInterceptor !== undefined && !isCodeEditorKeyInterceptor(keyInterceptor)) {
-    throw new TypeError(`${owner}: capabilities.keyInterceptor должен быть функцией. / ${owner}: capabilities.keyInterceptor must be a function.`)
-  }
-  return {
-    lineNumbers: validateBoolean(owner, 'capabilities.lineNumbers', record.lineNumbers),
-    indentation: {
-      tabSize: validateBoundedInteger(owner, 'capabilities.indentation.tabSize', indentation.tabSize, { minimum: 1, maximum: 16 }),
-      keyBehavior: validateExactString(owner, 'capabilities.indentation.keyBehavior', indentation.keyBehavior, CODE_EDITOR_KEY_BEHAVIORS),
-    },
-    ...(keyInterceptor === undefined ? {} : { keyInterceptor }),
-    cursorActivity: validateExactString(owner, 'capabilities.cursorActivity', record.cursorActivity, CODE_EDITOR_CURSOR_ACTIVITY_MODES),
-  }
-}
-
-export function validateCodeEditorViewport(owner: string, value: unknown): typeof CODE_EDITOR_VIEWPORTS[number] {
-  return validateExactString(owner, 'viewport', value, CODE_EDITOR_VIEWPORTS)
-}
-
-export function validateCodeEditorVariant(owner: string, value: unknown): typeof CODE_EDITOR_VARIANTS[number] {
-  return validateExactString(owner, 'variant', value, CODE_EDITOR_VARIANTS)
-}

package/src/internal/codeEditorExtensions.ts

@@ -1,27 +0,0 @@
-import type { ComputedRef, InjectionKey } from 'vue'
-import { inject, provide } from 'vue'
-import type { Extension } from '@codemirror/state'
-
-export type TrustedCodeEditorExtensionOwner = 'SSqlEditor'
-
-interface TrustedCodeEditorExtensionChannel {
-  owner: TrustedCodeEditorExtensionOwner
-  extensions: ComputedRef<readonly Extension[]>
-}
-
-const TRUSTED_CODE_EDITOR_EXTENSION_KEY: InjectionKey<TrustedCodeEditorExtensionChannel> = Symbol(
-  'sputnig-ui-kit-trusted-code-editor-extensions',
-)
-
-/** Internal-only CodeMirror extension channel for audited UI-kit adapters. */
-export function provideTrustedCodeEditorExtensions(
-  owner: TrustedCodeEditorExtensionOwner,
-  extensions: ComputedRef<readonly Extension[]>,
-): void {
-  provide(TRUSTED_CODE_EDITOR_EXTENSION_KEY, { owner, extensions })
-}
-
-/** Consumes extensions supplied by the nearest audited UI-kit adapter. */
-export function useTrustedCodeEditorExtensions(): TrustedCodeEditorExtensionChannel | null {
-  return inject(TRUSTED_CODE_EDITOR_EXTENSION_KEY, null)
-}

package/src/internal/codeLanguageIdentity.ts

@@ -1,89 +0,0 @@
-import {
-  type CodeEditorLanguageContract,
-  validateCodeEditorLanguage,
-} from './codeEditorContract'
-
-type NullableText = string | null | undefined
-
-const SPECIAL_FILENAMES: Readonly<Record<string, string>> = {
-  'cmakelists.txt': 'cmake',
-  'dockerfile': 'dockerfile',
-  'docker-compose.yml': 'yaml',
-  'docker-compose.yaml': 'yaml',
-  'compose.yml': 'yaml',
-  'compose.yaml': 'yaml',
-  '.env': 'properties',
-  '.env.example': 'properties',
-  '.env.local': 'properties',
-  '.env.development': 'properties',
-  '.env.production': 'properties',
-  'makefile': 'makefile',
-  'nginx.conf': 'nginx',
-}
-
-const LANGUAGE_ALIASES: Readonly<Record<string, string>> = {
-  bash: 'shell',
-  'c#': 'cs',
-  csharp: 'cs',
-  env: 'properties',
-  fish: 'shell',
-  handlebars: 'handlebars',
-  htm: 'html',
-  js: 'javascript',
-  jsonc: 'json',
-  json5: 'json',
-  log: 'text',
-  make: 'makefile',
-  md: 'markdown',
-  mk: 'makefile',
-  plaintext: 'text',
-  proto3: 'proto',
-  ps1: 'powershell',
-  psm1: 'powershell',
-  psd1: 'powershell',
-  py: 'python',
-  pyw: 'python',
-  pyi: 'python',
-  rbw: 'ruby',
-  sh: 'shell',
-  shellsession: 'shell',
-  ts: 'typescript',
-  text: 'text',
-  txt: 'text',
-  yaml: 'yaml',
-  yml: 'yaml',
-  zsh: 'shell',
-}
-
-function normalizeDetectedToken(value: NullableText): string | null {
-  if (!value) return null
-  const normalized = value.trim().toLowerCase().replace(/^\./u, '')
-  return normalized ? LANGUAGE_ALIASES[normalized] ?? normalized : null
-}
-
-function resolveLanguageFromFilePath(filePath: NullableText): string | null {
-  if (!filePath) return null
-  const normalizedPath = filePath.trim().toLowerCase()
-  if (!normalizedPath) return null
-  const basename = normalizedPath.split('/').pop() ?? normalizedPath
-  const special = SPECIAL_FILENAMES[basename]
-  if (special !== undefined) return special
-  if (basename.startsWith('dockerfile.')) return 'dockerfile'
-  if (!basename.includes('.')) return null
-  return normalizeDetectedToken(basename.split('.').pop())
-}
-
-/**
- * Разрешает стабильную language identity без загрузки editor/highlighter runtime.
- * Resolves stable language identity without loading editor or highlighter runtime.
- */
-export function resolveCodeLanguageKey(input: CodeEditorLanguageContract): string {
-  const language = validateCodeEditorLanguage('codeLanguages', input)
-  if (language.mode === 'explicit') return LANGUAGE_ALIASES[language.id] ?? language.id
-  const detected = resolveLanguageFromFilePath(language.filePath)
-  if (detected !== null) return detected
-  throw new RangeError(
-    `codeLanguages: невозможно определить язык по filePath ${JSON.stringify(language.filePath)}. `
-    + `/ codeLanguages: cannot detect a language from filePath ${JSON.stringify(language.filePath)}.`,
-  )
-}

package/src/internal/es2020.ts

@@ -1,50 +0,0 @@
-/** Проверяет собственное свойство без зависимости от ES2022 Object.hasOwn. / Checks an own property without the ES2022 Object.hasOwn API. */
-export function hasOwn(object: object, key: PropertyKey): boolean {
-  return Object.prototype.hasOwnProperty.call(object, key)
-}
-
-/** Возвращает последний элемент без зависимости от ES2022 Array.at. / Returns the last item without the ES2022 Array.at API. */
-export function lastItem<T>(items: readonly T[]): T | undefined {
-  return items.length > 0 ? items[items.length - 1] : undefined
-}
-
-/** Ошибка с ES2022-compatible cause, доступная в ES2020 runtime. / An ES2022-compatible error cause for ES2020 runtimes. */
-export type ErrorWithCause<T extends Error = Error> = T & { cause: unknown }
-
-/** Добавляет стандартный non-enumerable cause без требования ES2022 lib. / Adds the standard non-enumerable cause without requiring the ES2022 lib. */
-export function withErrorCause<T extends Error>(error: T, cause: unknown): ErrorWithCause<T> {
-  Object.defineProperty(error, 'cause', {
-    configurable: true,
-    value: cause,
-    writable: true,
-  })
-  return error as ErrorWithCause<T>
-}
-
-interface AggregateErrorLike extends Error {
-  readonly errors: readonly unknown[]
-}
-
-interface AggregateErrorConstructorLike {
-  new (errors: Iterable<unknown>, message?: string): AggregateErrorLike
-}
-
-class Es2020AggregateError extends Error implements AggregateErrorLike {
-  readonly errors: readonly unknown[]
-
-  constructor(errors: readonly unknown[], message: string) {
-    super(message)
-    this.name = 'AggregateError'
-    this.errors = [...errors]
-  }
-}
-
-/** Создаёт native AggregateError при наличии и точный ES2020 fallback иначе. / Creates a native AggregateError when available and an exact ES2020 fallback otherwise. */
-export function createAggregateError(errors: readonly unknown[], message: string): AggregateErrorLike {
-  const candidate: unknown = (globalThis as { AggregateError?: unknown }).AggregateError
-  if (typeof candidate === 'function') {
-    const AggregateErrorConstructor = candidate as AggregateErrorConstructorLike
-    return new AggregateErrorConstructor(errors, message)
-  }
-  return new Es2020AggregateError(errors, message)
-}

package/src/internal/feedbackPresentation.ts

@@ -1,136 +0,0 @@
-import type { Component } from 'vue'
-
-import { AlertTriangle, CheckCircle2, Info, LoaderCircle, XCircle } from '../components/icons/sputnigUiIcons'
-
-export type FeedbackTone = 'neutral' | 'info' | 'success' | 'warn' | 'danger'
-export type FeedbackSeverity = Exclude<FeedbackTone, 'neutral'>
-export type FeedbackLiveMode = 'off' | 'polite' | 'assertive' | 'auto'
-export type AsyncFeedbackStatus = 'loading' | 'empty' | 'error'
-export type FeedbackIndicatorState = FeedbackTone | 'progress'
-
-export interface FeedbackPresentation {
-  icon: Component
-  iconName: 'info' | 'check-circle' | 'alert-triangle' | 'x-circle'
-  fallbackTitle: string
-}
-
-export interface FeedbackLiveAttributes {
-  role?: 'status' | 'alert'
-  ariaLive?: 'polite' | 'assertive'
-  ariaAtomic?: 'true'
-}
-
-export interface AsyncFeedbackPresentation {
-  readonly tone: FeedbackTone
-  readonly icon: Component | null
-  readonly iconName: FeedbackPresentation['iconName'] | 'loader-circle' | null
-  readonly fallbackMessage: string
-  readonly busy: boolean
-  readonly live: Readonly<FeedbackLiveAttributes>
-}
-
-export interface FeedbackIndicatorPresentation {
-  readonly tone: FeedbackTone
-  readonly icon: Component
-  readonly iconName: FeedbackPresentation['iconName'] | 'loader-circle'
-  readonly fallbackTitle: string
-  readonly motion: 'static' | 'spin'
-}
-
-const presentations: Readonly<Record<FeedbackTone, Readonly<FeedbackPresentation>>> = {
-  neutral: { icon: Info, iconName: 'info', fallbackTitle: 'Статус' },
-  info: { icon: Info, iconName: 'info', fallbackTitle: 'Информация' },
-  success: { icon: CheckCircle2, iconName: 'check-circle', fallbackTitle: 'Успех' },
-  warn: { icon: AlertTriangle, iconName: 'alert-triangle', fallbackTitle: 'Предупреждение' },
-  danger: { icon: XCircle, iconName: 'x-circle', fallbackTitle: 'Ошибка' },
-}
-
-/**
- * Возвращает единую icon/title-презентацию для feedback tone.
- * Returns the canonical icon/title presentation for a feedback tone.
- */
-export function resolveFeedbackPresentation(tone: FeedbackTone): Readonly<FeedbackPresentation> {
-  return presentations[tone]
-}
-
-/**
- * Возвращает единственный icon/tone/motion contract для status indicator.
- * Returns the canonical icon/tone/motion contract for a status indicator.
- */
-export function resolveFeedbackIndicator(
-  state: FeedbackIndicatorState,
-): Readonly<FeedbackIndicatorPresentation> {
-  if (state === 'progress') {
-    return {
-      tone: 'info',
-      icon: LoaderCircle,
-      iconName: 'loader-circle',
-      fallbackTitle: 'Выполняется',
-      motion: 'spin',
-    }
-  }
-  const presentation = resolveFeedbackPresentation(state)
-  return {
-    tone: state,
-    icon: presentation.icon,
-    iconName: presentation.iconName,
-    fallbackTitle: presentation.fallbackTitle,
-    motion: 'static',
-  }
-}
-
-/**
- * Выражает live-region contract без привязки к визуальному компоненту.
- * Resolves live-region semantics independently from a visual component.
- */
-export function resolveFeedbackLive(
-  tone: FeedbackTone,
-  mode: FeedbackLiveMode,
-): Readonly<FeedbackLiveAttributes> {
-  if (mode === 'off') return {}
-  const politeness = mode === 'auto' ? (tone === 'danger' ? 'assertive' : 'polite') : mode
-  return {
-    role: politeness === 'assertive' ? 'alert' : 'status',
-    ariaLive: politeness,
-    ariaAtomic: 'true',
-  }
-}
-
-/**
- * Возвращает единый визуальный и live-region contract для async surface state.
- * Returns the canonical visual and live-region contract for an async surface state.
- */
-export function resolveAsyncFeedbackPresentation(
-  status: AsyncFeedbackStatus,
-): Readonly<AsyncFeedbackPresentation> {
-  if (status === 'loading') {
-    const progress = resolveFeedbackIndicator('progress')
-    return {
-      tone: progress.tone,
-      icon: progress.icon,
-      iconName: progress.iconName,
-      fallbackMessage: 'Загрузка…',
-      busy: true,
-      live: resolveFeedbackLive(progress.tone, 'auto'),
-    }
-  }
-  if (status === 'empty') {
-    return {
-      tone: 'neutral',
-      icon: null,
-      iconName: null,
-      fallbackMessage: 'Нет данных для отображения.',
-      busy: false,
-      live: resolveFeedbackLive('neutral', 'auto'),
-    }
-  }
-  const error = resolveFeedbackIndicator('danger')
-  return {
-    tone: 'danger',
-    icon: error.icon,
-    iconName: error.iconName,
-    fallbackMessage: error.fallbackTitle,
-    busy: false,
-    live: resolveFeedbackLive('danger', 'auto'),
-  }
-}

package/src/internal/fieldPresentation.ts

@@ -1,28 +0,0 @@
-import { computed, type ComputedRef } from 'vue'
-
-export const FIELD_REQUIRED_CLASS = 'ml-0.5 text-danger-600 dark:text-danger-400'
-export const FIELD_SUPPORT_CLASS = 'mt-1 min-w-0 whitespace-normal text-xs [overflow-wrap:anywhere]'
-export const FIELD_HELP_CLASS = `${FIELD_SUPPORT_CLASS} text-surface-500 dark:text-surface-400`
-export const FIELD_ERROR_CLASS = `${FIELD_SUPPORT_CLASS} text-danger-600 dark:text-danger-400`
-
-export interface FieldSupportingTextOptions {
-  readonly baseId: ComputedRef<string>
-  readonly hasHelp: () => boolean
-  readonly hasError: () => boolean
-}
-
-/**
- * Владеет exact ID и aria-describedby contract для help/error у field и fieldset.
- * Owns the exact help/error ID and aria-describedby contract for fields and fieldsets.
- */
-export function useFieldSupportingText(options: FieldSupportingTextOptions) {
-  const helpId = computed(() => `${options.baseId.value}-help`)
-  const errorId = computed(() => `${options.baseId.value}-error`)
-  const describedBy = computed(() => {
-    const ids: string[] = []
-    if (options.hasHelp()) ids.push(helpId.value)
-    if (options.hasError()) ids.push(errorId.value)
-    return ids.length > 0 ? ids.join(' ') : undefined
-  })
-  return { describedBy, errorId, helpId } as const
-}

package/src/internal/fieldSurface.ts

@@ -1,59 +0,0 @@
-import { validateBoolean, validateExactString, validateNonEmptyString } from './runtimeContract'
-
-const FIELD_SURFACE_KINDS = [
-  'text-input',
-  'textarea',
-  'inline-token-editor',
-  'combobox-trigger',
-] as const
-const FIELD_SURFACE_APPEARANCES = ['field', 'ghost', 'embedded'] as const
-
-/** Canonical owners sharing one field-surface visual contract. / Канонические владельцы общего визуального контракта field surface. */
-export type FieldSurfaceKind = typeof FIELD_SURFACE_KINDS[number]
-/** Canonical participation mode in the shared field surface. / Режим участия в общей field surface. */
-export type FieldSurfaceAppearance = typeof FIELD_SURFACE_APPEARANCES[number]
-
-export interface FieldSurfaceContract {
-  kind: FieldSurfaceKind
-  appearance: FieldSurfaceAppearance
-  invalid: boolean
-  disabled: boolean
-  readonly: boolean
-}
-
-export interface FieldSurfaceBindings {
-  'data-s-field-surface': FieldSurfaceKind
-  'data-s-field-appearance': FieldSurfaceAppearance
-  'data-s-field-invalid'?: 'true'
-  'data-s-field-disabled'?: 'true'
-  'data-s-field-readonly'?: 'true'
-}
-
-/**
- * Создаёт exact DOM bindings единого field-surface foundation без truthy coercion.
- * Creates exact DOM bindings for the shared field-surface foundation without truthy coercion.
- */
-export function resolveFieldSurfaceBindings(
-  owner: string,
-  contract: FieldSurfaceContract,
-): FieldSurfaceBindings {
-  validateNonEmptyString('fieldSurface', 'owner', owner)
-  const kind = validateExactString(owner, 'field surface kind', contract.kind, FIELD_SURFACE_KINDS)
-  const appearance = validateExactString(
-    owner,
-    'field surface appearance',
-    contract.appearance,
-    FIELD_SURFACE_APPEARANCES,
-  )
-  const invalid = validateBoolean(owner, 'field surface invalid', contract.invalid)
-  const disabled = validateBoolean(owner, 'field surface disabled', contract.disabled)
-  const readonly = validateBoolean(owner, 'field surface readonly', contract.readonly)
-
-  return {
-    'data-s-field-surface': kind,
-    'data-s-field-appearance': appearance,
-    ...(invalid ? { 'data-s-field-invalid': 'true' as const } : {}),
-    ...(disabled ? { 'data-s-field-disabled': 'true' as const } : {}),
-    ...(readonly ? { 'data-s-field-readonly': 'true' as const } : {}),
-  }
-}

package/src/internal/focusNavigation.ts

@@ -1,69 +0,0 @@
-const FOCUSABLE_SELECTOR = [
-  'a[href]',
-  'button:not([disabled])',
-  'textarea:not([disabled])',
-  'input:not([disabled])',
-  'select:not([disabled])',
-  '[contenteditable="true"]',
-  '[tabindex]:not([tabindex="-1"])',
-].join(', ')
-
-const isSemanticallyVisible = (element: HTMLElement): boolean => {
-  if (element.hidden || element.closest('[inert]') || element.closest('[aria-hidden="true"]')) return false
-  const style = window.getComputedStyle(element)
-  return style.display !== 'none' && style.visibility !== 'hidden'
-}
-
-/** Проверяет programmatic/browser focus owner без layout-эвристик. / Checks a programmatic/browser focus owner without layout heuristics. */
-export const isFocusableElement = (element: HTMLElement): boolean => (
-  element.matches(FOCUSABLE_SELECTOR) && isSemanticallyVisible(element)
-)
-
-/**
- * Поднимает произвольный event target до ближайшего canonical focus owner внутри optional boundary.
- * Lifts an arbitrary event target to the nearest canonical focus owner inside an optional boundary.
- */
-export const findFocusableOwner = (
-  target: EventTarget | null,
-  boundary?: ParentNode | null,
-): HTMLElement | null => {
-  const targetElement = target instanceof Element
-    ? target
-    : target instanceof Node
-      ? target.parentElement
-      : null
-  const owner = targetElement?.closest<HTMLElement>(FOCUSABLE_SELECTOR) ?? null
-  if (!owner || !isFocusableElement(owner)) return null
-  if (boundary instanceof Node && !boundary.contains(owner)) return null
-  return owner
-}
-
-export const getFocusableElements = (
-  root: ParentNode,
-  options: { requireLayout?: boolean } = {},
-): HTMLElement[] => [...root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)].filter((element) => {
-  if (!isFocusableElement(element)) return false
-  if (!options.requireLayout) return true
-  return element.offsetParent !== null || element.getClientRects().length > 0
-})
-
-export const findRelativeTabTarget = (
-  reference: HTMLElement,
-  scope: ParentNode,
-  excludedRoot: HTMLElement | null,
-  reverse: boolean,
-): HTMLElement | null => {
-  const candidates = getFocusableElements(scope).filter((element) => !excludedRoot?.contains(element))
-  if (candidates.length === 0) return null
-  const exactIndex = candidates.indexOf(reference)
-  if (exactIndex >= 0) {
-    const offset = reverse ? -1 : 1
-    return candidates[(exactIndex + offset + candidates.length) % candidates.length] ?? null
-  }
-
-  const ordered = reverse ? [...candidates].reverse() : candidates
-  const relation = reverse ? Node.DOCUMENT_POSITION_PRECEDING : Node.DOCUMENT_POSITION_FOLLOWING
-  return ordered.find((candidate) => Boolean(reference.compareDocumentPosition(candidate) & relation))
-    ?? ordered[0]
-    ?? null
-}