@pgcorp/ui-kit 0.10.0 → 0.10.2

package/src/composables/useSidebarPanelState.ts

@@ -1,611 +0,0 @@
-import { computed, getCurrentScope, onScopeDispose, reactive, readonly, watch } from 'vue';
-import { hasOwn, lastItem } from '../internal/es2020';
-
-import {
-  assertSidebarSectionsState,
-  type SectionState,
-} from '../components/shared/containers/sidebar';
-import type { UiPreferencesResetController } from './uiPreferencesReset';
-
-const DEFAULT_MIN_SIZE = 40;
-const MEMORY_STATE_RECOVERY = 'continue-with-memory-state' as const;
-export const SIDEBAR_PANEL_STATE_SCHEMA_VERSION = 2 as const;
-
-/**
- * Дефолтный layout-contract секции sidebar.
- * Default layout contract for a sidebar section.
- */
-export interface SectionDefaultConfig {
-  defaultIsOpen: boolean;
-  defaultSize: number | null;
-  minSize?: number;
-}
-
-/**
- * Точный storage-contract, нужный owner состояния sidebar.
- * Exact storage contract required by the sidebar state owner.
- */
-export interface SidebarPanelStateStorage {
-  getItem(key: string): string | null;
-  setItem(key: string, value: string): void;
-  removeItem(key: string): void;
-}
-
-export type SidebarPanelStatePersistenceErrorCode =
-  | 'storage-resolution-failed'
-  | 'read-failed'
-  | 'invalid-json'
-  | 'invalid-schema'
-  | 'write-failed'
-  | 'remove-failed';
-
-/**
- * Диагностируемая ошибка persistence с точными operation, storage key и path.
- * Diagnosable persistence error with exact operation, storage key, and path.
- */
-export class SidebarPanelStatePersistenceError extends Error {
-  readonly code: SidebarPanelStatePersistenceErrorCode;
-  readonly storageKey: string;
-  readonly path: string;
-  readonly cause: unknown;
-
-  constructor(options: {
-    code: SidebarPanelStatePersistenceErrorCode;
-    storageKey: string;
-    path?: string;
-    message: string;
-    cause: unknown;
-  }) {
-    super(options.message);
-    this.name = 'SidebarPanelStatePersistenceError';
-    this.code = options.code;
-    this.storageKey = options.storageKey;
-    this.path = options.path ?? '$';
-    this.cause = options.cause;
-  }
-}
-
-/**
- * Ошибка публичного runtime/config contract sidebar state.
- * Error in the public sidebar state runtime or configuration contract.
- */
-export class SidebarPanelStateContractError extends Error {
-  readonly path: string;
-
-  constructor(path: string, message: string) {
-    super(`Sidebar panel state contract violation at ${path}: ${message}`);
-    this.name = 'SidebarPanelStateContractError';
-    this.path = path;
-  }
-}
-
-/**
- * Явное решение consumer продолжить с in-memory state после диагностики persistence-ошибки.
- * Explicit consumer decision to continue with in-memory state after diagnosing a persistence error.
- */
-export type SidebarPanelStatePersistenceRecovery = typeof MEMORY_STATE_RECOVERY;
-
-/**
- * Явные runtime dependencies для persistence и scoped reset.
- * Explicit runtime dependencies for persistence and scoped reset.
- */
-export interface SidebarPanelStateRuntime {
-  resolveStorage(): SidebarPanelStateStorage | null;
-  resetController: UiPreferencesResetController;
-  recoverFromPersistenceError(
-    error: SidebarPanelStatePersistenceError,
-  ): SidebarPanelStatePersistenceRecovery;
-}
-
-type PersistedSectionState = Pick<SectionState, 'isOpen' | 'size'>;
-type PersistedSidebarPanelState = Record<string, PersistedSectionState>;
-type MutableSectionState = {
-  isOpen: boolean;
-  size: number | null;
-  minSize: number;
-};
-type PersistedSidebarPanelDocument = {
-  version: typeof SIDEBAR_PANEL_STATE_SCHEMA_VERSION;
-  sections: PersistedSidebarPanelState;
-};
-
-type DecodedPersistedState = {
-  sections: PersistedSidebarPanelState;
-  migratedFromVersion: 1 | null;
-};
-
-const isPlainRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value);
-
-const isValidSize = (value: unknown): value is number | null =>
-  value === null || (typeof value === 'number' && Number.isFinite(value) && value >= 0);
-
-function assertExactKeys(
-  value: Record<string, unknown>,
-  expectedKeys: readonly string[],
-  path: string,
-): void {
-  const actualKeys = Object.keys(value).sort();
-  const sortedExpectedKeys = [...expectedKeys].sort();
-  if (
-    actualKeys.length !== sortedExpectedKeys.length
-    || actualKeys.some((key, index) => key !== sortedExpectedKeys[index])
-  ) {
-    throw new SidebarPanelStateContractError(
-      path,
-      `expected keys [${sortedExpectedKeys.join(', ')}], received [${actualKeys.join(', ')}]`,
-    );
-  }
-}
-
-function assertSidebarLayoutState(value: unknown, path: string): asserts value is Record<string, SectionState> {
-  try {
-    assertSidebarSectionsState(value, 'useSidebarPanelState');
-  } catch (cause) {
-    throw new SidebarPanelStateContractError(
-      path,
-      cause instanceof Error ? cause.message : 'invalid sidebar layout state',
-    );
-  }
-}
-
-function validateDefaultConfig(
-  defaultConfig: Record<string, SectionDefaultConfig>,
-): readonly string[] {
-  if (!isPlainRecord(defaultConfig)) {
-    throw new SidebarPanelStateContractError('defaultConfig', 'expected an object');
-  }
-
-  const sectionKeys = Object.keys(defaultConfig);
-  if (sectionKeys.length === 0) {
-    throw new SidebarPanelStateContractError('defaultConfig', 'at least one section is required');
-  }
-
-  for (const sectionKey of sectionKeys) {
-    if (sectionKey.trim().length === 0) {
-      throw new SidebarPanelStateContractError('defaultConfig', 'section keys must not be empty');
-    }
-    const config = defaultConfig[sectionKey];
-    const path = `defaultConfig.${sectionKey}`;
-    if (!isPlainRecord(config)) {
-      throw new SidebarPanelStateContractError(path, 'expected an object');
-    }
-    const expectedKeys = config.minSize === undefined
-      ? ['defaultIsOpen', 'defaultSize']
-      : ['defaultIsOpen', 'defaultSize', 'minSize'];
-    assertExactKeys(config, expectedKeys, path);
-    if (typeof config.defaultIsOpen !== 'boolean') {
-      throw new SidebarPanelStateContractError(`${path}.defaultIsOpen`, 'expected a boolean');
-    }
-    if (!isValidSize(config.defaultSize)) {
-      throw new SidebarPanelStateContractError(`${path}.defaultSize`, 'expected null or a finite non-negative number');
-    }
-    if (
-      config.minSize !== undefined
-      && (typeof config.minSize !== 'number' || !Number.isFinite(config.minSize) || config.minSize <= 0)
-    ) {
-      throw new SidebarPanelStateContractError(`${path}.minSize`, 'expected a finite positive number');
-    }
-  }
-
-  assertSidebarLayoutState(
-    buildDefaultState(defaultConfig, sectionKeys, {}),
-    'defaultConfig',
-  );
-
-  return sectionKeys;
-}
-
-function validateRuntime(runtime: SidebarPanelStateRuntime): void {
-  if (!isPlainRecord(runtime)) {
-    throw new SidebarPanelStateContractError('runtime', 'expected an object');
-  }
-  assertExactKeys(
-    runtime,
-    ['recoverFromPersistenceError', 'resetController', 'resolveStorage'],
-    'runtime',
-  );
-  if (typeof runtime.resolveStorage !== 'function') {
-    throw new SidebarPanelStateContractError('runtime.resolveStorage', 'expected a function');
-  }
-  if (typeof runtime.recoverFromPersistenceError !== 'function') {
-    throw new SidebarPanelStateContractError(
-      'runtime.recoverFromPersistenceError',
-      'expected a function',
-    );
-  }
-  if (!isPlainRecord(runtime.resetController)) {
-    throw new SidebarPanelStateContractError('runtime.resetController', 'expected an object');
-  }
-  if (typeof runtime.resetController.subscribe !== 'function') {
-    throw new SidebarPanelStateContractError(
-      'runtime.resetController.subscribe',
-      'expected a function',
-    );
-  }
-  if (typeof runtime.resetController.requestReset !== 'function') {
-    throw new SidebarPanelStateContractError(
-      'runtime.resetController.requestReset',
-      'expected a function',
-    );
-  }
-}
-
-function decodePersistedState(
-  value: unknown,
-  sectionKeys: readonly string[],
-  basePath = '$',
-): PersistedSidebarPanelState {
-  if (!isPlainRecord(value)) {
-    throw new SidebarPanelStateContractError(basePath, 'expected an object');
-  }
-
-  const knownSections = new Set(sectionKeys);
-  const decoded: PersistedSidebarPanelState = {};
-  for (const [sectionKey, sectionValue] of Object.entries(value)) {
-    const path = `${basePath}.${sectionKey}`;
-    if (!knownSections.has(sectionKey)) {
-      throw new SidebarPanelStateContractError(path, 'unknown section');
-    }
-    if (!isPlainRecord(sectionValue)) {
-      throw new SidebarPanelStateContractError(path, 'expected an object');
-    }
-    assertExactKeys(sectionValue, ['isOpen', 'size'], path);
-    if (typeof sectionValue.isOpen !== 'boolean') {
-      throw new SidebarPanelStateContractError(`${path}.isOpen`, 'expected a boolean');
-    }
-    if (!isValidSize(sectionValue.size)) {
-      throw new SidebarPanelStateContractError(`${path}.size`, 'expected null or a finite non-negative number');
-    }
-    decoded[sectionKey] = {
-      isOpen: sectionValue.isOpen,
-      size: sectionValue.size,
-    };
-  }
-
-  return decoded;
-}
-
-function persistedDocument(sections: PersistedSidebarPanelState): PersistedSidebarPanelDocument {
-  return {
-    version: SIDEBAR_PANEL_STATE_SCHEMA_VERSION,
-    sections,
-  };
-}
-
-function preferredFlexibleSectionKey(
-  state: Record<string, SectionState>,
-  defaultConfig: Record<string, SectionDefaultConfig>,
-  sectionKeys: readonly string[],
-): string | null {
-  const openKeys = sectionKeys.filter((sectionKey) => state[sectionKey]?.isOpen);
-  if (openKeys.length === 0) return null;
-  const defaultFlexibleKey = sectionKeys.find((sectionKey) => {
-    const config = defaultConfig[sectionKey];
-    return config?.defaultIsOpen === true && config.defaultSize === null;
-  });
-  if (defaultFlexibleKey && state[defaultFlexibleKey]?.isOpen) return defaultFlexibleKey;
-  return lastItem(openKeys) ?? null;
-}
-
-/**
- * Мигрирует документ v1 по объявленному layout-контракту: default flexible owner сохраняет
- * гибкость, а остальные прежние flexible sections получают declared default/min size.
- * Migrates a v1 document using the declared layout contract: the default flexible owner keeps
- * flexibility while every other legacy flexible section receives its declared default/min size.
- */
-function migrateVersionOneState(
-  legacy: PersistedSidebarPanelState,
-  defaultConfig: Record<string, SectionDefaultConfig>,
-  sectionKeys: readonly string[],
-): PersistedSidebarPanelState {
-  const fullState = buildDefaultState(defaultConfig, sectionKeys, legacy);
-  const flexibleKey = preferredFlexibleSectionKey(fullState, defaultConfig, sectionKeys);
-  const migratedState: Record<string, SectionState> = Object.fromEntries(
-    sectionKeys.map((sectionKey) => {
-      const section = fullState[sectionKey]!;
-      const config = defaultConfig[sectionKey]!;
-      const size = section.isOpen && sectionKey === flexibleKey
-        ? null
-        : section.isOpen && section.size === null
-          ? config.defaultSize ?? config.minSize ?? DEFAULT_MIN_SIZE
-          : section.size;
-      return [sectionKey, { ...section, size }];
-    }),
-  );
-  assertSidebarLayoutState(migratedState, '$.sections');
-  return Object.fromEntries(sectionKeys.map((sectionKey) => {
-    const section = migratedState[sectionKey]!;
-    return [sectionKey, { isOpen: section.isOpen, size: section.size }];
-  }));
-}
-
-function decodePersistedDocument(
-  value: unknown,
-  defaultConfig: Record<string, SectionDefaultConfig>,
-  sectionKeys: readonly string[],
-): DecodedPersistedState {
-  if (!isPlainRecord(value)) {
-    throw new SidebarPanelStateContractError('$', 'expected an object');
-  }
-  if (hasOwn(value, 'version') || hasOwn(value, 'sections')) {
-    assertExactKeys(value, ['sections', 'version'], '$');
-    if (value.version !== SIDEBAR_PANEL_STATE_SCHEMA_VERSION) {
-      throw new SidebarPanelStateContractError(
-        '$.version',
-        `expected ${SIDEBAR_PANEL_STATE_SCHEMA_VERSION}, received ${String(value.version)}`,
-      );
-    }
-    const sections = decodePersistedState(value.sections, sectionKeys, '$.sections');
-    assertSidebarLayoutState(
-      buildDefaultState(defaultConfig, sectionKeys, sections),
-      '$.sections',
-    );
-    return { sections, migratedFromVersion: null };
-  }
-  const legacy = decodePersistedState(value, sectionKeys);
-  return {
-    sections: migrateVersionOneState(legacy, defaultConfig, sectionKeys),
-    migratedFromVersion: 1,
-  };
-}
-
-function validateNextState(
-  value: Record<string, SectionState>,
-  defaultConfig: Record<string, SectionDefaultConfig>,
-  sectionKeys: readonly string[],
-): void {
-  if (!isPlainRecord(value)) {
-    throw new SidebarPanelStateContractError('newState', 'expected an object');
-  }
-  assertExactKeys(value, sectionKeys, 'newState');
-
-  for (const sectionKey of sectionKeys) {
-    const section = value[sectionKey];
-    const path = `newState.${sectionKey}`;
-    if (!isPlainRecord(section)) {
-      throw new SidebarPanelStateContractError(path, 'expected an object');
-    }
-    assertExactKeys(section, ['isOpen', 'size', 'minSize'], path);
-    if (typeof section.isOpen !== 'boolean') {
-      throw new SidebarPanelStateContractError(`${path}.isOpen`, 'expected a boolean');
-    }
-    if (!isValidSize(section.size)) {
-      throw new SidebarPanelStateContractError(`${path}.size`, 'expected null or a finite non-negative number');
-    }
-    const expectedMinSize = defaultConfig[sectionKey]?.minSize ?? DEFAULT_MIN_SIZE;
-    if (section.minSize !== expectedMinSize) {
-      throw new SidebarPanelStateContractError(
-        `${path}.minSize`,
-        `expected configured value ${expectedMinSize}, received ${String(section.minSize)}`,
-      );
-    }
-  }
-  assertSidebarLayoutState(value, 'newState');
-}
-
-function buildDefaultState(
-  defaultConfig: Record<string, SectionDefaultConfig>,
-  sectionKeys: readonly string[],
-  persistedState: PersistedSidebarPanelState,
-): Record<string, SectionState> {
-  return Object.fromEntries(sectionKeys.map((sectionKey) => {
-    const config = defaultConfig[sectionKey]!;
-    const persisted = persistedState[sectionKey];
-    return [sectionKey, {
-      isOpen: persisted?.isOpen ?? config.defaultIsOpen,
-      size: persisted === undefined ? config.defaultSize : persisted.size,
-      minSize: config.minSize ?? DEFAULT_MIN_SIZE,
-    }];
-  }));
-}
-
-/**
- * Управляет disclosure/size state всех секций sidebar через один validated owner.
- * Owns disclosure/size state for every sidebar section through one validated owner.
- *
- * Persisted v2 document содержит exact `{ version, sections }`. Валидный unversioned v1 record
- * мигрирует один раз по объявленным default/min layout values; невалидный v2 целиком удаляется
- * только после явного recovery-решения runtime.
- * The persisted v2 document is exact `{ version, sections }`. A valid unversioned v1 record is
- * migrated once from declared default/min layout values; invalid v2 data is removed as a whole
- * only after the runtime explicitly accepts memory-state recovery.
- */
-export function useSidebarPanelState(
-  storageKey: string,
-  defaultConfig: Record<string, SectionDefaultConfig>,
-  runtime: SidebarPanelStateRuntime,
-) {
-  if (typeof storageKey !== 'string' || storageKey.trim().length === 0) {
-    throw new SidebarPanelStateContractError('storageKey', 'expected a non-empty string');
-  }
-  validateRuntime(runtime);
-  if (!getCurrentScope()) {
-    throw new SidebarPanelStateContractError(
-      'runtime.scope',
-      'useSidebarPanelState must run inside an active Vue effect scope',
-    );
-  }
-
-  const sectionKeys = validateDefaultConfig(defaultConfig);
-
-  const recover = (error: SidebarPanelStatePersistenceError): void => {
-    const resolution = runtime.recoverFromPersistenceError(error);
-    if (resolution !== MEMORY_STATE_RECOVERY) {
-      throw new SidebarPanelStateContractError(
-        'runtime.recoverFromPersistenceError',
-        `expected "${MEMORY_STATE_RECOVERY}", received ${String(resolution)}`,
-      );
-    }
-  };
-
-  let storage: SidebarPanelStateStorage | null = null;
-  try {
-    storage = runtime.resolveStorage();
-  } catch (cause) {
-    recover(new SidebarPanelStatePersistenceError({
-      code: 'storage-resolution-failed',
-      storageKey,
-      message: `Unable to resolve sidebar state storage for "${storageKey}".`,
-      cause,
-    }));
-  }
-
-  const removePersistedState = (): void => {
-    if (!storage) {
-      return;
-    }
-    try {
-      storage.removeItem(storageKey);
-    } catch (cause) {
-      recover(new SidebarPanelStatePersistenceError({
-        code: 'remove-failed',
-        storageKey,
-        message: `Unable to remove sidebar state for "${storageKey}".`,
-        cause,
-      }));
-    }
-  };
-
-  const writePersistedState = (sections: PersistedSidebarPanelState): void => {
-    if (!storage) return;
-    try {
-      storage.setItem(storageKey, JSON.stringify(persistedDocument(sections)));
-    } catch (cause) {
-      recover(new SidebarPanelStatePersistenceError({
-        code: 'write-failed',
-        storageKey,
-        message: `Unable to write sidebar state for "${storageKey}".`,
-        cause,
-      }));
-    }
-  };
-
-  const readPersistedState = (): PersistedSidebarPanelState => {
-    if (!storage) {
-      return {};
-    }
-
-    let rawValue: string | null;
-    try {
-      rawValue = storage.getItem(storageKey);
-    } catch (cause) {
-      recover(new SidebarPanelStatePersistenceError({
-        code: 'read-failed',
-        storageKey,
-        message: `Unable to read sidebar state for "${storageKey}".`,
-        cause,
-      }));
-      return {};
-    }
-    if (rawValue === null) {
-      return {};
-    }
-
-    let parsedValue: unknown;
-    try {
-      parsedValue = JSON.parse(rawValue) as unknown;
-    } catch (cause) {
-      recover(new SidebarPanelStatePersistenceError({
-        code: 'invalid-json',
-        storageKey,
-        message: `Persisted sidebar state for "${storageKey}" is not valid JSON.`,
-        cause,
-      }));
-      removePersistedState();
-      return {};
-    }
-
-    try {
-      const decoded = decodePersistedDocument(parsedValue, defaultConfig, sectionKeys);
-      if (decoded.migratedFromVersion === 1) writePersistedState(decoded.sections);
-      return decoded.sections;
-    } catch (cause) {
-      recover(new SidebarPanelStatePersistenceError({
-        code: 'invalid-schema',
-        storageKey,
-        path: cause instanceof SidebarPanelStateContractError ? cause.path : '$',
-        message: `Persisted sidebar state for "${storageKey}" does not match its schema.`,
-        cause,
-      }));
-      removePersistedState();
-      return {};
-    }
-  };
-
-  const sectionsState = reactive<Record<string, SectionState>>(
-    buildDefaultState(defaultConfig, sectionKeys, readPersistedState()),
-  );
-
-  const stateToStore = computed<PersistedSidebarPanelDocument>(() =>
-    persistedDocument(Object.fromEntries(sectionKeys.map((sectionKey) => {
-      const section = sectionsState[sectionKey]!;
-      return [sectionKey, { isOpen: section.isOpen, size: section.size }];
-    }))),
-  );
-
-  watch(stateToStore, (nextState) => {
-    writePersistedState(nextState.sections);
-  }, { deep: true });
-
-  const updateSections = (newState: Record<string, SectionState>): void => {
-    validateNextState(newState, defaultConfig, sectionKeys);
-    for (const sectionKey of sectionKeys) {
-      sectionsState[sectionKey] = { ...newState[sectionKey]! };
-    }
-  };
-
-  const toggleSection = (sectionKey: string): void => {
-    const section = sectionsState[sectionKey];
-    if (!section) {
-      throw new SidebarPanelStateContractError(
-        `sectionsState.${sectionKey}`,
-        'cannot toggle an unknown section',
-      );
-    }
-    const nextState: Record<string, MutableSectionState> = Object.fromEntries(
-      sectionKeys.map((key) => [key, { ...sectionsState[key]! }]),
-    );
-    const nextSection = nextState[sectionKey]!;
-    const otherOpenKeys = sectionKeys.filter((key) => key !== sectionKey && nextState[key]?.isOpen);
-    if (nextSection.isOpen) {
-      nextSection.isOpen = false;
-      if (nextSection.size === null && otherOpenKeys.length > 0) {
-        const sectionIndex = sectionKeys.indexOf(sectionKey);
-        const nextFlexibleKey = [...otherOpenKeys].sort((left, right) => (
-          Math.abs(sectionKeys.indexOf(left) - sectionIndex)
-          - Math.abs(sectionKeys.indexOf(right) - sectionIndex)
-        ))[0]!;
-        nextState[nextFlexibleKey] = { ...nextState[nextFlexibleKey]!, size: null };
-      }
-    } else {
-      nextSection.isOpen = true;
-      if (otherOpenKeys.length === 0) {
-        nextSection.size = null;
-      } else if (nextSection.size === null) {
-        const config = defaultConfig[sectionKey]!;
-        nextSection.size = config.defaultSize ?? config.minSize ?? DEFAULT_MIN_SIZE;
-      }
-    }
-    validateNextState(nextState, defaultConfig, sectionKeys);
-    for (const key of sectionKeys) sectionsState[key] = nextState[key]!;
-  };
-
-  const resetSections = (): void => {
-    removePersistedState();
-    const defaultState = buildDefaultState(defaultConfig, sectionKeys, {});
-    for (const sectionKey of sectionKeys) {
-      sectionsState[sectionKey] = defaultState[sectionKey]!;
-    }
-  };
-
-  const unsubscribeFromReset = runtime.resetController.subscribe(resetSections);
-  onScopeDispose(unsubscribeFromReset);
-
-  return {
-    sectionsState: readonly(sectionsState),
-    updateSections,
-    toggleSection,
-    resetSections,
-  };
-}

package/src/composables/useUiKitLocale.ts

@@ -1,17 +0,0 @@
-import { resolveUiKitLocaleContext, type UiKitLocaleContext } from '../internal/localeContext'
-
-/** Returns the immutable locale contract scoped to the current Vue application subtree. */
-export function useUiKitLocale(): UiKitLocaleContext {
-  return resolveUiKitLocaleContext()
-}
-
-export type {
-  UiKitLocale,
-  UiKitMessageKey,
-  UiKitMessageParameters,
-  UiKitMessages,
-  UiKitMessagesOverride,
-  UiKitTranslate,
-} from '../locales/locale'
-export { UI_KIT_LOCALES } from '../locales/locale'
-export { UI_KIT_MESSAGES, UI_KIT_MESSAGE_KEYS } from '../locales/messages'