@pgcorp/ui-kit 0.1.0

package/src/internal/ownedAttrs.ts

@@ -0,0 +1,464 @@
+import {
+  useAttrs,
+  type AnchorHTMLAttributes,
+  type HTMLAttributes,
+  type InputHTMLAttributes,
+  type TextareaHTMLAttributes,
+} from 'vue'
+
+type OwnedAttributeValueKind =
+  | 'aria'
+  | 'aria-boolean'
+  | 'aria-current'
+  | 'aria-haspopup'
+  | 'aria-pressed'
+  | 'boolean-attribute'
+  | 'data'
+  | 'input-mode'
+  | 'listener'
+  | 'string'
+  | 'string-or-boolean'
+  | 'string-or-number'
+
+type OwnedAttributeSchema = Readonly<Record<string, OwnedAttributeValueKind>>
+
+function defineOwnedAttributeSchema<const Schema extends OwnedAttributeSchema>(schema: Schema): Readonly<Schema> {
+  return Object.freeze(schema)
+}
+
+/**
+ * Exact runtime allowlist каждого public owner.
+ * Exact runtime allowlist for every public owner.
+ *
+ * Пустая схема означает, что компонент не принимает fallthrough attrs: его API целиком выражен props/emits/slots.
+ * An empty schema means that the component accepts no fallthrough attrs: props/emits/slots express its entire API.
+ */
+export const ownedAttributeSchemas = Object.freeze({
+  SAppShell: defineOwnedAttributeSchema({}),
+  SDockRegion: defineOwnedAttributeSchema({}),
+  SResizeHandle: defineOwnedAttributeSchema({
+    'data-test-id': 'data',
+  }),
+  SSideMenuButton: defineOwnedAttributeSchema({
+    'data-testid': 'data',
+  }),
+  SSideMenuRail: defineOwnedAttributeSchema({
+    'data-testid': 'data',
+  }),
+  SStack: defineOwnedAttributeSchema({}),
+  SStatusBarShell: defineOwnedAttributeSchema({}),
+  SWorkbenchLayout: defineOwnedAttributeSchema({}),
+  SWorkbenchPanelShell: defineOwnedAttributeSchema({}),
+  SKanbanCard: defineOwnedAttributeSchema({
+    'data-testid': 'data',
+  }),
+  SKanbanLane: defineOwnedAttributeSchema({}),
+  STree: defineOwnedAttributeSchema({
+    'data-testid': 'data',
+  }),
+  SCloudChrome: defineOwnedAttributeSchema({
+    'data-chat-chrome-drop-zone': 'data',
+    'data-testid': 'data',
+  }),
+  SCloudChromeEmpty: defineOwnedAttributeSchema({}),
+  SCloudChromeRow: defineOwnedAttributeSchema({}),
+  SCollapsiblePanel: defineOwnedAttributeSchema({
+    'data-testid': 'data',
+  }),
+  SDrawer: defineOwnedAttributeSchema({}),
+  SFormGrid: defineOwnedAttributeSchema({}),
+  SFormGridItem: defineOwnedAttributeSchema({}),
+  SLeftSidebar: defineOwnedAttributeSchema({}),
+  SModal: defineOwnedAttributeSchema({
+    'data-testid': 'data',
+  }),
+  SPageHeader: defineOwnedAttributeSchema({}),
+  SPanel: defineOwnedAttributeSchema({
+    'data-testid': 'data',
+  }),
+  SPopover: defineOwnedAttributeSchema({
+    id: 'string',
+    'aria-label': 'string',
+    'data-testid': 'data',
+    onClick: 'listener',
+  }),
+  SSidebarGroup: defineOwnedAttributeSchema({}),
+  SSidebarSection: defineOwnedAttributeSchema({}),
+  SButton: defineOwnedAttributeSchema({
+    'aria-controls': 'string',
+    'aria-describedby': 'string',
+    'aria-current': 'aria-current',
+    'aria-expanded': 'aria-boolean',
+    'aria-haspopup': 'aria-haspopup',
+    'aria-hidden': 'aria-boolean',
+    'aria-keyshortcuts': 'string',
+    'aria-label': 'string',
+    'aria-pressed': 'aria-pressed',
+    'aria-selected': 'aria-boolean',
+    'data-s-popover-trigger': 'data',
+    'data-s-drag-handle': 'data',
+    'data-sidebar-section-toggle': 'data',
+    'data-state': 'data',
+    'data-test': 'data',
+    'data-testid': 'data',
+    'data-tree-selection-control': 'data',
+    autofocus: 'boolean-attribute',
+    id: 'string',
+    onClick: 'listener',
+    onFocusin: 'listener',
+    onFocusout: 'listener',
+    onKeydown: 'listener',
+    onMousedown: 'listener',
+    onPointercancel: 'listener',
+    onPointerdown: 'listener',
+    onPointerenter: 'listener',
+    onPointerleave: 'listener',
+    onPointerup: 'listener',
+    role: 'string',
+    tabindex: 'string-or-number',
+    title: 'string',
+  }),
+  SCheckbox: defineOwnedAttributeSchema({
+    'aria-label': 'string',
+    'aria-describedby': 'string',
+    'data-testid': 'data',
+    onClick: 'listener',
+    onPointerdown: 'listener',
+    tabindex: 'string-or-number',
+  }),
+  SCheckboxGroup: defineOwnedAttributeSchema({
+    'aria-describedby': 'string',
+    'data-testid': 'data',
+  }),
+  SChoiceCards: defineOwnedAttributeSchema({
+    'aria-describedby': 'string',
+    'data-testid': 'data',
+  }),
+  SColorSelect: defineOwnedAttributeSchema({
+    'aria-label': 'string',
+  }),
+  SDragHandle: defineOwnedAttributeSchema({
+    'data-testid': 'data',
+  }),
+  SContextMenu: defineOwnedAttributeSchema({}),
+  SContextToggleButton: defineOwnedAttributeSchema({}),
+  SField: defineOwnedAttributeSchema({}),
+  SFieldGroup: defineOwnedAttributeSchema({
+    'aria-describedby': 'string',
+    'data-testid': 'data',
+  }),
+  SFieldLabel: defineOwnedAttributeSchema({
+    'aria-label': 'string',
+    'data-testid': 'data',
+  }),
+  SDropdownMenu: defineOwnedAttributeSchema({
+    'aria-label': 'string',
+    'data-testid': 'data',
+    id: 'string',
+    title: 'string',
+  }),
+  SInputText: defineOwnedAttributeSchema({
+    'aria-describedby': 'string',
+    'aria-invalid': 'aria-boolean',
+    'aria-label': 'string',
+    'data-testid': 'data',
+    autocomplete: 'string',
+    inputmode: 'input-mode',
+    list: 'string',
+    max: 'string-or-number',
+    min: 'string-or-number',
+    onBlur: 'listener',
+    onFocus: 'listener',
+    onKeydown: 'listener',
+    onKeyup: 'listener',
+    pattern: 'string',
+    step: 'string-or-number',
+    title: 'string',
+  }),
+  SInlineTokenEditor: defineOwnedAttributeSchema({
+    'aria-describedby': 'string',
+    'aria-label': 'string',
+    'aria-labelledby': 'string',
+    'data-testid': 'data',
+    autocomplete: 'string',
+  }),
+  SInteractiveSurface: defineOwnedAttributeSchema({}),
+  SLink: defineOwnedAttributeSchema({
+    'aria-label': 'string',
+    'data-s-app-shell-brand-passive': 'data',
+    'data-testid': 'data',
+    download: 'string-or-boolean',
+    title: 'string',
+  }),
+  SListbox: defineOwnedAttributeSchema({
+    'aria-describedby': 'string',
+    'data-testid': 'data',
+  }),
+  SMarker: defineOwnedAttributeSchema({}),
+  SMenuSurface: defineOwnedAttributeSchema({
+    id: 'string',
+  }),
+  SSegmentedControl: defineOwnedAttributeSchema({
+    'aria-describedby': 'string',
+    'data-testid': 'data',
+  }),
+  SSelect: defineOwnedAttributeSchema({
+    'aria-describedby': 'string',
+    'aria-label': 'string',
+    'data-task-mapping-internal-value': 'data',
+    'data-task-mapping-kind': 'data',
+    'data-test': 'data',
+    'data-testid': 'data',
+  }),
+  STextarea: defineOwnedAttributeSchema({
+    'aria-describedby': 'string',
+    'aria-label': 'string',
+    'data-testid': 'data',
+    autocomplete: 'string',
+    onBlur: 'listener',
+  }),
+  SActionList: defineOwnedAttributeSchema({}),
+  SActionListItem: defineOwnedAttributeSchema({
+    'data-testid': 'data',
+    role: 'string',
+  }),
+  SActionCard: defineOwnedAttributeSchema({
+    'data-testid': 'data',
+    onFocusout: 'listener',
+  }),
+  SBadge: defineOwnedAttributeSchema({
+    'data-testid': 'data',
+    title: 'string',
+  }),
+  SCodeBlock: defineOwnedAttributeSchema({
+    'aria-label': 'string',
+    'data-testid': 'data',
+  }),
+  SCodeEditor: defineOwnedAttributeSchema({
+    'aria-label': 'string',
+    'aria-labelledby': 'string',
+    autofocus: 'boolean-attribute',
+  }),
+  SCodeSearchPanel: defineOwnedAttributeSchema({}),
+  SCopyField: defineOwnedAttributeSchema({}),
+  SDocBlock: defineOwnedAttributeSchema({}),
+  SEmptyState: defineOwnedAttributeSchema({}),
+  SExpandableText: defineOwnedAttributeSchema({
+    'data-testid': 'data',
+  }),
+  SJsonTree: defineOwnedAttributeSchema({}),
+  SKeyValueGrid: defineOwnedAttributeSchema({}),
+  SLinkedSystemsList: defineOwnedAttributeSchema({}),
+  SMessage: defineOwnedAttributeSchema({
+    'data-testid': 'data',
+  }),
+  SMetricCard: defineOwnedAttributeSchema({}),
+  SProgressBar: defineOwnedAttributeSchema({}),
+  SProgressIndicator: defineOwnedAttributeSchema({}),
+  SSectionHeader: defineOwnedAttributeSchema({}),
+  SStatus: defineOwnedAttributeSchema({}),
+  STable: defineOwnedAttributeSchema({}),
+  SToastContainer: defineOwnedAttributeSchema({}),
+  STooltip: defineOwnedAttributeSchema({}),
+  STooltipAnchor: defineOwnedAttributeSchema({
+    'aria-describedby': 'string',
+    'data-testid': 'data',
+    id: 'string',
+  }),
+  SVirtualList: defineOwnedAttributeSchema({}),
+  SAsyncState: defineOwnedAttributeSchema({}),
+  SDataGrid: defineOwnedAttributeSchema({}),
+  SSqlEditor: defineOwnedAttributeSchema({}),
+  SGraphViewport: defineOwnedAttributeSchema({}),
+  SBottomNav: defineOwnedAttributeSchema({}),
+  SBreadcrumbs: defineOwnedAttributeSchema({
+    'aria-label': 'string',
+  }),
+  SCatalogNavigator: defineOwnedAttributeSchema({
+    'aria-label': 'string',
+  }),
+  STab: defineOwnedAttributeSchema({
+    'aria-label': 'string',
+    'data-terminal-id': 'data',
+    'data-testid': 'data',
+    onDblclick: 'listener',
+    onMousedown: 'listener',
+    title: 'string',
+  }),
+  STabList: defineOwnedAttributeSchema({
+    'aria-label': 'string',
+  }),
+  STabPanel: defineOwnedAttributeSchema({
+    'data-terminal-id': 'data',
+    'data-testid': 'data',
+  }),
+  STabPanels: defineOwnedAttributeSchema({}),
+  STabs: defineOwnedAttributeSchema({
+    'aria-label': 'string',
+  }),
+  SWizardSteps: defineOwnedAttributeSchema({
+    'data-wizard-owner': 'data',
+  }),
+  SPersonaProjectPicker: defineOwnedAttributeSchema({}),
+  SPersonaRunWorkbench: defineOwnedAttributeSchema({}),
+} as const)
+
+export type OwnedAttributeComponent = keyof typeof ownedAttributeSchemas
+type OwnedAttributeName<Component extends OwnedAttributeComponent> = keyof (typeof ownedAttributeSchemas)[Component] & string
+type OwnedAttributeKind<Component extends OwnedAttributeComponent, Name extends OwnedAttributeName<Component>> =
+  (typeof ownedAttributeSchemas)[Component][Name] & OwnedAttributeValueKind
+
+type KindAttributeValue<Kind extends OwnedAttributeValueKind> =
+  Kind extends 'listener' ? (payload: Event) => void
+    : Kind extends 'string' ? string
+      : Kind extends 'string-or-boolean' ? string | boolean
+        : Kind extends 'string-or-number' ? string | number
+          : Kind extends 'data' | 'aria' ? string | number | boolean
+            : Kind extends 'aria-boolean' ? boolean | 'true' | 'false'
+              : Kind extends 'aria-current' ? boolean | 'page' | 'step' | 'location' | 'date' | 'time'
+                : Kind extends 'aria-haspopup' ? boolean | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog'
+                  : Kind extends 'aria-pressed' ? boolean | 'mixed'
+                    : Kind extends 'input-mode' ? 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url'
+            : Kind extends 'boolean-attribute' ? string | boolean
+              : never
+
+type OwnedAttributeValue<Name extends string, Kind extends OwnedAttributeValueKind> =
+  Name extends keyof HTMLAttributes ? NonNullable<HTMLAttributes[Name]>
+    : Name extends keyof InputHTMLAttributes ? NonNullable<InputHTMLAttributes[Name]>
+      : Name extends keyof TextareaHTMLAttributes ? NonNullable<TextareaHTMLAttributes[Name]>
+        : Name extends keyof AnchorHTMLAttributes ? NonNullable<AnchorHTMLAttributes[Name]>
+          : KindAttributeValue<Kind>
+
+export type OwnedAttributeBindings<Component extends OwnedAttributeComponent> = Readonly<Partial<{
+  [Name in OwnedAttributeName<Component>]: OwnedAttributeValue<Name, OwnedAttributeKind<Component, Name>>
+}>>
+
+export interface OwnedAttrsOptions<Component extends OwnedAttributeComponent> {
+  /** Имя public-компонента для диагностики контракта. / Public component name used in contract diagnostics. */
+  component: Component
+  /** Семантический/native-элемент, владеющий атрибутами. / Semantic/native element that owns the attributes. */
+  owner: string
+}
+
+export interface OwnedAttrsContract<Component extends OwnedAttributeComponent> {
+  /**
+   * Возвращает проверенные exact non-prop атрибуты для семантического owner.
+   * Returns validated exact non-prop attributes for the semantic owner.
+   */
+  bindings: () => OwnedAttributeBindings<Component>
+  /**
+   * Отклоняет любые attrs, когда у состояния нет семантического owner.
+   * Rejects every attr when the current state has no semantic owner.
+   */
+  reject: (reason: string) => void
+  /** Читает разрешённый строковый attr и отклоняет неверный runtime-тип. / Reads an allowed string attr and rejects an invalid runtime type. */
+  string: (name: OwnedAttributeName<Component>) => string | undefined
+}
+
+/**
+ * Объединяет ARIA ID-reference lists без повторов. / Merges ARIA ID-reference lists without duplicates.
+ */
+export function mergeIdReferences(...references: Array<string | undefined>): string | undefined {
+  const tokens = references.flatMap((reference) => reference?.trim().split(/\s+/).filter(Boolean) ?? [])
+  return tokens.length > 0 ? [...new Set(tokens)].join(' ') : undefined
+}
+
+function isListener(value: unknown): boolean {
+  return typeof value === 'function'
+    || (Array.isArray(value) && value.length > 0 && value.every((candidate) => typeof candidate === 'function'))
+}
+
+function isAllowedAttributeValue(kind: OwnedAttributeValueKind, value: unknown): boolean {
+  if (value === undefined || value === null) return true
+  if (kind === 'listener') return isListener(value)
+  if (kind === 'string') return typeof value === 'string'
+  if (kind === 'aria-boolean') return typeof value === 'boolean' || value === 'true' || value === 'false'
+  if (kind === 'aria-current') {
+    return typeof value === 'boolean' || ['page', 'step', 'location', 'date', 'time'].includes(String(value))
+  }
+  if (kind === 'aria-haspopup') {
+    return typeof value === 'boolean' || ['menu', 'listbox', 'tree', 'grid', 'dialog'].includes(String(value))
+  }
+  if (kind === 'aria-pressed') return typeof value === 'boolean' || value === 'mixed'
+  if (kind === 'input-mode') {
+    return ['none', 'text', 'decimal', 'numeric', 'tel', 'search', 'email', 'url'].includes(String(value))
+  }
+  if (kind === 'string-or-boolean' || kind === 'boolean-attribute') {
+    return typeof value === 'string' || typeof value === 'boolean'
+  }
+  if (kind === 'string-or-number') return typeof value === 'string' || typeof value === 'number'
+  return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+}
+
+function attributeBoundaryError(component: string, owner: string, message: string): Error {
+  return new Error(`${component}: ${message} на границе ${owner}. / ${message} at the ${owner} boundary.`)
+}
+
+/**
+ * Маршрутизирует только exact-audited native/data/ARIA/listener attrs к одному owner.
+ * Routes only exact-audited native/data/ARIA/listener attrs to one owner.
+ */
+export function useOwnedAttrs<Component extends OwnedAttributeComponent>(
+  options: OwnedAttrsOptions<Component>,
+): OwnedAttrsContract<Component> {
+  const attrs = useAttrs()
+  const schema: OwnedAttributeSchema = ownedAttributeSchemas[options.component]
+
+  const validate = (): void => {
+    for (const [name, value] of Object.entries(attrs)) {
+      if (name === 'class' || name === 'style') {
+        throw attributeBoundaryError(
+          options.component,
+          options.owner,
+          `raw "${name}" запрещён; атрибут "${name}" не объявлен в exact owned-attrs schema; используйте типизированные props/tokens UI-kit или consumer layout wrapper. Raw "${name}" is forbidden and is not declared by the exact owned-attrs schema; use typed UI-kit props/tokens or a consumer layout wrapper`,
+        )
+      }
+      const kind = schema[name]
+      if (!kind) {
+        throw attributeBoundaryError(
+          options.component,
+          options.owner,
+          `атрибут "${name}" не объявлен в exact owned-attrs schema; используйте типизированные props/emits/tokens UI-kit или consumer layout wrapper. Attribute "${name}" is not declared by the exact owned-attrs schema; use typed UI-kit props/emits/tokens or a consumer layout wrapper`,
+        )
+      }
+      if (!isAllowedAttributeValue(kind, value)) {
+        throw attributeBoundaryError(
+          options.component,
+          options.owner,
+          `атрибут "${name}" имеет недопустимый runtime-тип ${typeof value}; ожидается ${kind}. Attribute "${name}" has invalid runtime type ${typeof value}; expected ${kind}`,
+        )
+      }
+    }
+  }
+
+  const bindings = (): OwnedAttributeBindings<Component> => {
+    validate()
+    return Object.fromEntries(Object.entries(attrs)) as OwnedAttributeBindings<Component>
+  }
+
+  const string = (name: OwnedAttributeName<Component>): string | undefined => {
+    const kind = schema[name]
+    if (kind !== 'string') {
+      throw attributeBoundaryError(
+        options.component,
+        options.owner,
+        `атрибут "${name}" не объявлен строковым. Attribute "${name}" is not declared as a string`,
+      )
+    }
+    validate()
+    const value = attrs[name]
+    if (value === undefined || value === null) return undefined
+    return value as string
+  }
+
+  const reject = (reason: string): void => {
+    const names = Object.keys(attrs)
+    if (names.length === 0) return
+    throw new Error(
+      `${options.component}: attrs ${names.map((name) => `"${name}"`).join(', ')} не имеют владельца (${reason}). `
+      + `Attributes ${names.map((name) => `"${name}"`).join(', ')} have no owner (${reason}).`,
+    )
+  }
+
+  return { bindings, reject, string }
+}

package/src/internal/passiveContentContract.ts

@@ -0,0 +1,129 @@
+import {
+  defineComponent,
+  inject,
+  onBeforeUnmount,
+  provide,
+  watchEffect,
+  type InjectionKey,
+  type PropType,
+} from 'vue'
+
+export interface PassiveContentContract {
+  /** Имя компонента-владельца для точной runtime-диагностики. / Owner name used in precise runtime diagnostics. */
+  owner: string
+  /** Имя пассивной области публичного slot contract. / Name of the passive public slot region. */
+  region: string
+  /** Отключает запрет, когда поверхность семантически не интерактивна. / Disables the guard while the surface is semantically passive. */
+  active?: () => boolean
+  /** Подсказка о правильном sibling API владельца. / Guidance to the owner's sibling API. */
+  guidance?: string
+}
+
+export interface InteractiveLeafContract {
+  /** Канонический leaf owner интерактивного поведения. / Canonical leaf owner of the interactive behavior. */
+  owner: string
+  /** Учитывает leaf только когда он действительно интерактивен. / Counts the leaf only while it is actually interactive. */
+  active?: () => boolean
+}
+
+interface InteractiveLeafRegistration extends InteractiveLeafContract {
+  readonly id: symbol
+}
+
+interface PassiveContentBoundary {
+  register: (registration: InteractiveLeafRegistration) => () => void
+  assert: () => void
+}
+
+const passiveContentBoundaryKey: InjectionKey<PassiveContentBoundary> = Symbol('passiveContentBoundary')
+
+/**
+ * Ограничивает typed passive-content contract точным slot-поддеревом без дополнительного DOM-узла.
+ * Scopes a typed passive-content contract to the exact slot subtree without adding a DOM node.
+ */
+export const PassiveContentBoundary = defineComponent({
+  name: 'PassiveContentBoundary',
+  props: {
+    contract: {
+      type: Object as PropType<PassiveContentContract>,
+      required: true,
+    },
+  },
+  setup(props, { slots }) {
+    usePassiveContentContract(props.contract)
+    return () => slots.default?.()
+  },
+})
+
+function passiveContentError(
+  contract: PassiveContentContract,
+  registration: InteractiveLeafRegistration,
+): Error {
+  const guidance = contract.guidance ? ` ${contract.guidance}` : ''
+  return new Error(
+    `${contract.owner}: ${contract.region} не допускает интерактивный leaf ${registration.owner}; `
+    + `интерактивное действие должно быть sibling-узлом.`
+    + ` / ${contract.owner}: ${contract.region} does not allow the interactive leaf `
+    + `${registration.owner}; render the interactive action as a sibling.${guidance}`,
+  )
+}
+
+/**
+ * Создаёт typed registration boundary для пассивного slot-контента без DOM-инспекции.
+ * Creates a typed registration boundary for passive slot content without DOM inspection.
+ */
+export function usePassiveContentContract(contract: PassiveContentContract): void {
+  const parentBoundary = inject(passiveContentBoundaryKey, null)
+  const registrations = new Map<symbol, InteractiveLeafRegistration>()
+
+  const assert = (): void => {
+    if (contract.active?.() === false) return
+    const interactive = [...registrations.values()].find((registration) => registration.active?.() !== false)
+    if (interactive) throw passiveContentError(contract, interactive)
+  }
+
+  const boundary: PassiveContentBoundary = {
+    register: (registration) => {
+      if (registrations.has(registration.id)) {
+        throw new Error(`${contract.owner}: duplicate interactive leaf registration from ${registration.owner}`)
+      }
+      registrations.set(registration.id, registration)
+      let unregisterParent: (() => void) | undefined
+      try {
+        assert()
+        unregisterParent = parentBoundary?.register(registration)
+      } catch (error) {
+        registrations.delete(registration.id)
+        unregisterParent?.()
+        throw error
+      }
+      return () => {
+        registrations.delete(registration.id)
+        unregisterParent?.()
+      }
+    },
+    assert,
+  }
+
+  provide(passiveContentBoundaryKey, boundary)
+  watchEffect(assert)
+  onBeforeUnmount(() => registrations.clear())
+}
+
+/**
+ * Регистрирует UI-kit leaf во всех родительских passive boundaries.
+ * Registers a UI-kit leaf with every parent passive boundary.
+ */
+export function useInteractiveLeafRegistration(contract: InteractiveLeafContract): void {
+  const boundary = inject(passiveContentBoundaryKey, null)
+  if (!boundary) return
+  const registration: InteractiveLeafRegistration = {
+    ...contract,
+    id: Symbol(contract.owner),
+  }
+  const unregister = boundary.register(registration)
+  watchEffect(() => {
+    if (contract.active?.() !== false) boundary.assert()
+  })
+  onBeforeUnmount(unregister)
+}

package/src/internal/pointerInteractionLease.ts

@@ -0,0 +1,81 @@
+export type PointerInteractionCursor = 'col-resize' | 'row-resize'
+
+export interface PointerInteractionLeaseOptions {
+  cursor: PointerInteractionCursor
+}
+
+export interface PointerInteractionLease {
+  release: () => void
+}
+
+interface ActivePointerInteraction {
+  id: symbol
+  cursor: PointerInteractionCursor
+}
+
+const activeInteractions: ActivePointerInteraction[] = []
+let lockedBody: HTMLElement | null = null
+let preservedCursor = ''
+let preservedUserSelect = ''
+
+const applyActiveInteraction = (): void => {
+  const interaction = activeInteractions.at(-1)
+  if (!lockedBody || !interaction) return
+  lockedBody.style.cursor = interaction.cursor
+  lockedBody.style.userSelect = 'none'
+}
+
+const restoreBodyContract = (): void => {
+  if (!lockedBody) return
+  lockedBody.style.cursor = preservedCursor
+  lockedBody.style.userSelect = preservedUserSelect
+  lockedBody = null
+  preservedCursor = ''
+  preservedUserSelect = ''
+}
+
+/**
+ * Захватывает общий cursor/user-select контракт на время pointer-взаимодействия.
+ * Acquires the shared cursor/user-select contract for one pointer interaction.
+ */
+export function acquirePointerInteractionLease(
+  options: PointerInteractionLeaseOptions,
+): PointerInteractionLease {
+  if (typeof document === 'undefined') {
+    throw new Error('pointerInteractionLease: document недоступен вне браузерного runtime')
+  }
+
+  const body = document.body
+  if (activeInteractions.length === 0) {
+    lockedBody = body
+    preservedCursor = body.style.cursor
+    preservedUserSelect = body.style.userSelect
+  } else if (lockedBody !== body) {
+    throw new Error('pointerInteractionLease: document.body изменился во время активного interaction')
+  }
+
+  const interaction: ActivePointerInteraction = {
+    id: Symbol('pointer-interaction'),
+    cursor: options.cursor,
+  }
+  let active = true
+  activeInteractions.push(interaction)
+  applyActiveInteraction()
+
+  return {
+    release: () => {
+      if (!active) return
+      active = false
+      const index = activeInteractions.findIndex(candidate => candidate.id === interaction.id)
+      if (index < 0) {
+        throw new Error('pointerInteractionLease: активный lease отсутствует в реестре')
+      }
+      activeInteractions.splice(index, 1)
+      if (activeInteractions.length === 0) {
+        restoreBodyContract()
+        return
+      }
+      applyActiveInteraction()
+    },
+  }
+}