@pgcorp/ui-kit 0.1.0

package/src/components/shared/containers/SSidebarSection.vue

@@ -0,0 +1,268 @@
+<template>
+  <div
+    v-bind="ownedAttrs.bindings()"
+    ref="sectionEl"
+    class="s-sidebar-section-wrapper"
+    :class="{ 's-sidebar-section-wrapper--resizable-before': isResizableBefore }"
+    :style="style"
+  >
+    <!-- Разделитель должен быть ПЕРЕД секцией, а не внутри нее. -->
+    <SResizeHandle
+      v-if="isResizableBefore"
+      orientation="horizontal"
+      label="Изменить высоту секций"
+      :value="resizeContract.value"
+      :min="resizeContract.min"
+      :max="resizeContract.max"
+      :step="10"
+      :data-test-id="resizeContract.testId"
+      @resize-start="handleResizeStart"
+      @resize="handleResize"
+      @resize-end="handleResizeEnd"
+    />
+    <div class="s-sidebar-section">
+      <div class="s-sidebar-section-header" :class="{ 's-sidebar-section-header--mobile': layout === 'mobile' }">
+        <div class="s-sidebar-section-trigger">
+          <SButton
+            :id="triggerId"
+            :size="layout === 'mobile' ? 'xs' : 'sm'"
+            severity="secondary"
+            appearance="ghost"
+            shape="row"
+            width="full"
+            content-align="start"
+            data-sidebar-section-toggle
+            :disabled="disabled"
+            :disclosure="{ expanded: isOpen, controls: panelId, iconPlacement: 'leading' }"
+            @click="disclosure.toggle"
+          >
+            <SDisclosureSummary
+              :title="summary"
+              :typography="summaryTypography"
+              :casing="summaryCase"
+              :state="summaryState"
+              :facts="summaryFacts"
+              :badges="summaryBadges"
+              :status="summaryStatus"
+            />
+          </SButton>
+        </div>
+        <div v-if="hasActions" class="s-sidebar-section-actions">
+          <slot name="actions" />
+        </div>
+      </div>
+      <div
+        v-if="isOpen"
+        :id="panelId"
+        :aria-labelledby="triggerId"
+        role="region"
+        tabindex="0"
+        class="s-sidebar-section-content"
+      >
+        <slot />
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, inject, onBeforeUnmount, onMounted, ref, useId, watch } from 'vue';
+
+import { useDisclosure } from '../../../composables/useDisclosure';
+import { useOwnedAttrs } from '../../../internal/ownedAttrs';
+import SResizeHandle from '../../layout/SResizeHandle.vue';
+import {
+  sidebarGroupContextKey,
+  type RegisteredSidebarSection,
+} from '../_internal/sidebarGroupContext';
+import SDisclosureSummary from '../_internal/SDisclosureSummary.vue';
+import SButton from '../controls/SButton.vue';
+import type {
+  SDisclosureSummaryBadge,
+  SDisclosureSummaryCase,
+  SDisclosureSummaryFact,
+  SDisclosureSummaryState,
+  SDisclosureSummaryStatus,
+  SDisclosureSummaryTypography,
+} from './disclosureSummary';
+
+defineOptions({
+  name: 'SSidebarSection',
+  inheritAttrs: false,
+});
+
+const props = withDefaults(defineProps<{
+  summary: string;
+  summaryTypography?: SDisclosureSummaryTypography;
+  summaryCase?: SDisclosureSummaryCase;
+  summaryState?: SDisclosureSummaryState;
+  summaryFacts?: readonly SDisclosureSummaryFact[];
+  summaryBadges?: readonly SDisclosureSummaryBadge[];
+  summaryStatus?: SDisclosureSummaryStatus;
+  stateKey: string;
+  layout?: 'desktop' | 'mobile';
+  disabled?: boolean;
+}>(), {
+  summaryTypography: 'strong',
+  summaryCase: 'uppercase',
+  summaryState: undefined,
+  summaryFacts: () => [],
+  summaryBadges: () => [],
+  summaryStatus: undefined,
+  layout: 'desktop',
+  disabled: false,
+});
+
+const slots = defineSlots<{
+  default(): unknown;
+  actions?(): unknown;
+}>();
+
+const sectionEl = ref<HTMLDivElement | null>(null);
+const ownedAttrs = useOwnedAttrs({ component: 'SSidebarSection', owner: 'sidebar section wrapper' });
+const hasActions = computed(() => Boolean(slots.actions));
+const injectedGroupContext = inject(sidebarGroupContextKey);
+if (!injectedGroupContext) {
+  throw new Error('SSidebarSection: component must be rendered inside SSidebarGroup');
+}
+const groupContext = injectedGroupContext;
+if (props.stateKey.trim().length === 0) {
+  throw new TypeError('SSidebarSection: stateKey must be a non-empty string');
+}
+const registeredStateKey = props.stateKey;
+const disclosureBaseId = `s-sidebar-section-${useId()}-${props.stateKey.replace(/[^a-zA-Z0-9_-]/g, '-')}`;
+let unregisterSection: (() => void) | null = null;
+const isRegistered = ref(false);
+
+onMounted(() => {
+  const element = sectionEl.value;
+  if (!element) {
+    throw new Error('SSidebarSection: section wrapper is unavailable during mount');
+  }
+  unregisterSection = groupContext.registerSection({ key: registeredStateKey, element });
+  isRegistered.value = true;
+});
+
+onBeforeUnmount(() => {
+  isRegistered.value = false;
+  unregisterSection?.();
+  unregisterSection = null;
+});
+
+watch(() => props.stateKey, (stateKey) => {
+  if (stateKey !== registeredStateKey) {
+    throw new Error(
+      `SSidebarSection: stateKey is immutable after setup; received '${registeredStateKey}' -> '${stateKey}'`,
+    );
+  }
+});
+
+const sectionIndex = computed(() => {
+  const index = groupContext.orderedSections.value.findIndex(
+    (section) => section.key === registeredStateKey,
+  );
+  if (isRegistered.value && index < 0) {
+    throw new Error(
+      `SSidebarSection: registered section '${registeredStateKey}' is absent from group order`,
+    );
+  }
+  return index;
+});
+
+const isOpen = computed(() => {
+  const state = groupContext.sectionsState.value[registeredStateKey];
+  if (!state) {
+    throw new Error(
+      `SSidebarSection: sectionsState has no entry for stateKey '${registeredStateKey}'`,
+    );
+  }
+  return state.isOpen;
+});
+const disclosure = useDisclosure({
+  id: disclosureBaseId,
+  open: isOpen,
+  disabled: () => props.disabled ?? false,
+  onUpdate: () => groupContext.toggleSection(registeredStateKey),
+});
+const { triggerId, panelId } = disclosure;
+
+const style = computed(() => {
+  return groupContext.getSectionStyle(registeredStateKey);
+});
+
+const isResizableBefore = computed(() => {
+  if (sectionIndex.value <= 0 || !isOpen.value) {
+    return false;
+  }
+  const sections = groupContext.orderedSections.value;
+  for (let i = sectionIndex.value - 1; i >= 0; i--) {
+    if (sections[i]?.state.isOpen) return true;
+  }
+  return false;
+});
+
+const topSectionIndex = computed(() => {
+  for (let index = sectionIndex.value - 1; index >= 0; index--) {
+    if (groupContext.orderedSections.value[index]?.state.isOpen) return index;
+  }
+  return -1;
+});
+
+function measuredHeight(section: RegisteredSidebarSection): number {
+  const height = section.element.offsetHeight;
+  if (!Number.isFinite(height) || height < 0) {
+    throw new RangeError(
+      `SSidebarSection: sections.${section.key}.offsetHeight must be a non-negative finite number`,
+    );
+  }
+  return height;
+}
+
+function resizePair(): readonly [RegisteredSidebarSection, RegisteredSidebarSection] {
+  if (topSectionIndex.value < 0 || sectionIndex.value < 0) {
+    throw new Error(`SSidebarSection: resize pair is unavailable for section '${registeredStateKey}'`);
+  }
+  const sections = groupContext.orderedSections.value;
+  const top = sections[topSectionIndex.value];
+  const bottom = sections[sectionIndex.value];
+  if (!top || !bottom) {
+    throw new Error(
+      `SSidebarSection: resize pair indices are outside mounted group order for section '${registeredStateKey}'`,
+    );
+  }
+  return [top, bottom];
+}
+
+const resizeContract = computed(() => {
+  const [top, bottom] = resizePair();
+  const value = Math.max(top.state.minSize, top.state.size ?? measuredHeight(top));
+  const bottomSize = Math.max(
+    bottom.state.minSize,
+    bottom.state.size ?? measuredHeight(bottom),
+  );
+  const pairSize = value + bottomSize;
+  return {
+    value,
+    min: top.state.minSize,
+    max: Math.max(top.state.minSize, pairSize - bottom.state.minSize),
+    testId: `sidebar-resize-${top.key}-${bottom.key}`,
+  };
+});
+
+function handleResizeStart(): void {
+  const [top, bottom] = resizePair();
+  groupContext.beginResize(top.key, bottom.key);
+}
+
+function handleResize(value: number): void {
+  const [top, bottom] = resizePair();
+  groupContext.resizeSections(top.key, bottom.key, value);
+}
+
+function handleResizeEnd(): void {
+  const [top, bottom] = resizePair();
+  groupContext.finishResize(top.key, bottom.key);
+}
+</script>
+
+<style lang="postcss" src="./SSidebarSection.css" scoped></style>

package/src/components/shared/containers/disclosureSummary.ts

@@ -0,0 +1,48 @@
+import type { BadgeSeverity } from '../data-display/SBadge.vue'
+import type { StatusTone } from '../data-display/SStatus.vue'
+
+/** Типографика заголовка disclosure. / Disclosure summary typography. */
+export type SDisclosureSummaryTypography = 'default' | 'strong' | 'mono'
+
+/** Регистр заголовка disclosure. / Disclosure summary letter case. */
+export type SDisclosureSummaryCase = 'sentence' | 'uppercase'
+
+/** Семантическое состояние с системной иконкой. / Semantic state with a system-owned icon. */
+export type SDisclosureSummaryState = 'neutral' | 'progress' | 'success' | 'warn' | 'danger'
+
+/** Семантический тон факта. / Semantic fact tone. */
+export type SDisclosureSummaryTone = 'neutral' | 'info' | 'success' | 'warn' | 'danger'
+
+/** Короткая пара label/value в заголовке. / Compact label/value pair in a summary. */
+export interface SDisclosureSummaryFact {
+  /** Стабильная identity факта, не зависящая от отображаемого значения. / Stable fact identity independent of its displayed value. */
+  id: string
+  /** Необязательная подпись значения. / Optional value label. */
+  label?: string
+  /** Отображаемое непустое значение. / Non-empty displayed value. */
+  value: string | number
+  /** Семантический тон факта. / Semantic tone of the fact. */
+  tone?: SDisclosureSummaryTone
+}
+
+/** Неинтерактивный badge в заголовке. / Non-interactive summary badge. */
+export interface SDisclosureSummaryBadge {
+  /** Стабильная identity badge, не зависящая от отображаемой подписи. / Stable badge identity independent of its displayed label. */
+  id: string
+  /** Непустая подпись badge. / Non-empty badge label. */
+  label: string | number
+  /** Семантическая важность badge. / Semantic badge severity. */
+  severity?: BadgeSeverity
+  /** Дополнительная нативная подсказка. / Additional native tooltip. */
+  title?: string
+}
+
+/** Текстовый статус в конце заголовка. / Trailing text status in a summary. */
+export interface SDisclosureSummaryStatus {
+  /** Непустая подпись статуса. / Non-empty status label. */
+  label: string
+  /** Семантический тон статуса. / Semantic status tone. */
+  tone?: StatusTone
+  /** Дополнительная нативная подсказка. / Additional native tooltip. */
+  title?: string
+}

package/src/components/shared/containers/popover.ts

@@ -0,0 +1,72 @@
+import type { InteractiveElementRefTarget } from '../../../internal/interactiveElement'
+import type { SButtonDisclosure } from '../controls/SButton.vue'
+
+/**
+ * Режим реакции custom trigger на единый click-контракт.
+ * Custom-trigger activation mode for the unified click contract.
+ */
+export type SPopoverTriggerActivation = 'toggle' | 'manual'
+
+/**
+ * Допустимая цель callback-ref custom trigger.
+ * Supported callback-ref target for a custom trigger.
+ */
+export type SPopoverTriggerRefTarget = InteractiveElementRefTarget
+
+/**
+ * Полный контракт для `v-bind` непосредственно на button-root custom trigger.
+ * Complete contract for `v-bind` directly on the custom trigger button root.
+ */
+export interface SPopoverTriggerBinding {
+  readonly ref: (target: SPopoverTriggerRefTarget) => void
+  readonly disclosure: SButtonDisclosure
+  readonly 'aria-expanded': boolean
+  readonly 'aria-haspopup': 'dialog'
+  readonly 'aria-controls': string
+  readonly onClick: (event: MouseEvent) => void
+}
+
+/**
+ * Binder создаёт один контракт для каждого уникального trigger id.
+ * The binder creates one contract for every unique trigger id.
+ */
+export type SPopoverTriggerBinder = (
+  triggerId: string,
+  activation?: SPopoverTriggerActivation,
+) => SPopoverTriggerBinding
+
+/**
+ * Публичный scoped-контракт custom trigger.
+ * Public scoped contract for custom triggers.
+ */
+export interface SPopoverTriggerSlotProps {
+  readonly bindTrigger: SPopoverTriggerBinder
+  readonly open: (triggerId?: string) => void
+  readonly close: () => void
+  readonly isOpen: boolean
+}
+
+/**
+ * Содержимое built-in trigger получает только наблюдаемое состояние.
+ * Built-in trigger content receives observable state only.
+ */
+export interface SPopoverDefaultSlotProps {
+  readonly isOpen: boolean
+}
+
+/**
+ * Панель может запросить явное закрытие с возвратом focus к trigger.
+ * The panel may explicitly close and restore focus to its trigger.
+ */
+export interface SPopoverPanelSlotProps {
+  readonly close: () => void
+}
+
+/**
+ * Публичный programmatic API использует зарегистрированный anchor.
+ * The public programmatic API uses a registered anchor.
+ */
+export interface SPopoverPublicApi {
+  open: (triggerId?: string) => void
+  close: () => void
+}

package/src/components/shared/containers/sidebar.ts

@@ -0,0 +1,206 @@
+/**
+ * Состояние размера и раскрытия одной sidebar-секции.
+ * Size and disclosure state of one sidebar section.
+ */
+export interface SectionState {
+  readonly isOpen: boolean;
+  readonly size: number | null;
+  readonly minSize: number;
+}
+
+/**
+ * Точная controlled-state карта под управлением consumer.
+ * Exact controlled state map owned by the consumer.
+ */
+export type SidebarSectionsState = Readonly<Record<string, Readonly<SectionState>>>;
+
+/** Exact payload map общего владельца sidebar-секций. / Exact payload map of the shared sidebar-section owner. */
+export interface SidebarGroupEmits {
+  'update-sections': [state: SidebarSectionsState];
+  'toggle-section': [key: string];
+}
+
+/**
+ * Одна точная immutable-замена секции в controlled transition.
+ * One exact immutable section replacement in a controlled transition.
+ */
+export interface SidebarSectionReplacement {
+  readonly key: string;
+  readonly state: Readonly<SectionState>;
+}
+
+const SECTION_STATE_FIELDS = Object.freeze(['isOpen', 'minSize', 'size'] as const);
+
+function assertPlainDataRecord(
+  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 a plain data record`);
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new TypeError(`${owner}: ${coordinate} must be a plain data record`);
+  }
+  if (Object.getOwnPropertySymbols(value).length > 0) {
+    throw new TypeError(`${owner}: ${coordinate} must not contain symbol properties`);
+  }
+  for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) {
+    if (!descriptor.enumerable || !('value' in descriptor)) {
+      throw new TypeError(`${owner}: ${coordinate}.${key} must be an enumerable data property`);
+    }
+  }
+}
+
+function assertExactSectionState(
+  owner: string,
+  coordinate: string,
+  value: unknown,
+): asserts value is SectionState {
+  assertPlainDataRecord(owner, coordinate, value);
+  const keys = Object.keys(value).sort();
+  if (
+    keys.length !== SECTION_STATE_FIELDS.length
+    || keys.some((key, index) => key !== SECTION_STATE_FIELDS[index])
+  ) {
+    throw new TypeError(
+      `${owner}: ${coordinate} must contain exactly [${SECTION_STATE_FIELDS.join(', ')}]`,
+    );
+  }
+  if (typeof value.isOpen !== 'boolean') {
+    throw new TypeError(`${owner}: ${coordinate}.isOpen must be a boolean`);
+  }
+  if (typeof value.minSize !== 'number' || !Number.isFinite(value.minSize) || value.minSize < 0) {
+    throw new TypeError(`${owner}: ${coordinate}.minSize must be a non-negative finite number`);
+  }
+  if (
+    value.size !== null
+    && (
+      typeof value.size !== 'number'
+      || !Number.isFinite(value.size)
+      || value.size < value.minSize
+    )
+  ) {
+    throw new TypeError(
+      `${owner}: ${coordinate}.size must be null or a finite number not below minSize`,
+    );
+  }
+}
+
+/**
+ * Проверяет полный точный controlled-контракт геометрии sidebar.
+ * Validates the complete exact controlled sidebar geometry contract.
+ */
+export function assertSidebarSectionsState(
+  state: unknown,
+  owner = 'SSidebarGroup',
+): asserts state is SidebarSectionsState {
+  assertPlainDataRecord(owner, 'sectionsState', state);
+  const openSections: SectionState[] = [];
+  for (const [key, section] of Object.entries(state)) {
+    if (key.trim().length === 0) {
+      throw new TypeError(`${owner}: section keys must be non-empty strings`);
+    }
+    assertExactSectionState(owner, `sectionsState.${key}`, section);
+    if (section.isOpen) openSections.push(section);
+  }
+  const flexibleOpenCount = openSections.filter((section) => section.size === null).length;
+  if (openSections.length > 0 && flexibleOpenCount !== 1) {
+    throw new TypeError(
+      `${owner}: exactly one open section must have size=null; received ${flexibleOpenCount}`,
+    );
+  }
+}
+
+function immutableSectionState(state: Readonly<SectionState>): Readonly<SectionState> {
+  return Object.freeze({
+    isOpen: state.isOpen,
+    size: state.size,
+    minSize: state.minSize,
+  });
+}
+
+/**
+ * Проверяет, копирует и глубоко замораживает полное controlled-state значение.
+ * Validates, copies, and deeply freezes one complete controlled state value.
+ */
+export function createSidebarSectionsState(
+  state: unknown,
+  owner = 'SSidebarGroup',
+): SidebarSectionsState {
+  assertSidebarSectionsState(state, owner);
+  return Object.freeze(Object.fromEntries(
+    Object.entries(state).map(([key, section]) => [key, immutableSectionState(section)]),
+  ));
+}
+
+/**
+ * Создаёт deeply immutable controlled transition без мутации или сериализации входа.
+ * Creates one deeply immutable controlled transition without mutating or serializing its input.
+ */
+export function createSidebarSectionsTransition(
+  current: SidebarSectionsState,
+  replacements: readonly SidebarSectionReplacement[],
+): SidebarSectionsState {
+  assertSidebarSectionsState(current);
+  if (!Array.isArray(replacements) || replacements.length === 0) {
+    throw new TypeError('SSidebarGroup: a transition requires at least one section replacement');
+  }
+  const replacementsByKey = new Map<string, Readonly<SectionState>>();
+  for (const [index, replacement] of replacements.entries()) {
+    assertPlainDataRecord('SSidebarGroup', `replacements[${index}]`, replacement);
+    const replacementKeys = Object.keys(replacement).sort();
+    if (
+      replacementKeys.length !== 2
+      || replacementKeys[0] !== 'key'
+      || replacementKeys[1] !== 'state'
+    ) {
+      throw new TypeError(
+        `SSidebarGroup: replacements[${index}] must contain exactly [key, state]`,
+      );
+    }
+    if (typeof replacement.key !== 'string' || replacement.key.trim().length === 0) {
+      throw new TypeError(`SSidebarGroup: replacements[${index}].key must be a non-empty string`);
+    }
+    if (!Object.hasOwn(current, replacement.key)) {
+      throw new Error(`SSidebarGroup: cannot replace unknown section '${replacement.key}'`);
+    }
+    if (replacementsByKey.has(replacement.key)) {
+      throw new Error(`SSidebarGroup: duplicate replacement for section '${replacement.key}'`);
+    }
+    assertExactSectionState(
+      'SSidebarGroup',
+      `replacements[${index}].state`,
+      replacement.state,
+    );
+    replacementsByKey.set(replacement.key, replacement.state);
+  }
+
+  const next = Object.fromEntries(Object.entries(current).map(([key, state]) => [
+    key,
+    immutableSectionState(replacementsByKey.get(key) ?? state),
+  ]));
+  return createSidebarSectionsState(next);
+}
+
+/**
+ * Сравнивает точные public state fields без coercion.
+ * Compares the exact public state fields without coercion.
+ */
+export function sidebarSectionsStateEqual(
+  left: SidebarSectionsState,
+  right: SidebarSectionsState,
+): boolean {
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  return leftKeys.length === rightKeys.length && leftKeys.every((key) => {
+    const leftSection = left[key];
+    const rightSection = right[key];
+    return leftSection !== undefined
+      && rightSection !== undefined
+      && leftSection.isOpen === rightSection.isOpen
+      && leftSection.size === rightSection.size
+      && leftSection.minSize === rightSection.minSize;
+  });
+}