@pgcorp/ui-kit 0.1.0

package/src/composables/useSidebarPanelState.ts

@@ -0,0 +1,610 @@
+import { computed, getCurrentScope, onScopeDispose, reactive, readonly, watch } from 'vue';
+
+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 openKeys.at(-1) ?? 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 (Object.hasOwn(value, 'version') || Object.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,
+  };
+}