@pgcorp/ui-kit 0.1.0

package/src/theme.ts

@@ -0,0 +1,449 @@
+export const themeFamilies = ['classic', 'pink', 'green'] as const;
+export type ThemeFamily = (typeof themeFamilies)[number];
+
+export const themeModes = ['light', 'dark'] as const;
+export type ThemeMode = (typeof themeModes)[number];
+
+export const themePreferences = ['light', 'dark', 'pink-light', 'pink-dark', 'green-light', 'green-dark'] as const;
+export type ThemePreference = (typeof themePreferences)[number];
+
+export const themeIds = ['classic-light', 'classic-dark', 'pink-light', 'pink-dark', 'green-light', 'green-dark'] as const;
+export type ThemeId = (typeof themeIds)[number];
+
+export interface StoredThemeState {
+  themeId: ThemeId;
+}
+
+export interface ThemeVariant {
+  id: ThemeId;
+  family: ThemeFamily;
+  mode: ThemeMode;
+  dataTheme: ThemePreference;
+  browserThemeColor: string;
+  statusBarStyle: 'default' | 'black-translucent';
+  label: string;
+  familyLabel: string;
+  modeLabel: string;
+}
+
+export const defaultThemeId: ThemeId = 'classic-light';
+
+export const themeVariants = [
+  {
+    id: 'classic-light',
+    family: 'classic',
+    mode: 'light',
+    dataTheme: 'light',
+    browserThemeColor: '#f8fafc',
+    statusBarStyle: 'default',
+    label: 'Классическая светлая',
+    familyLabel: 'Классическая',
+    modeLabel: 'Светлая',
+  },
+  {
+    id: 'classic-dark',
+    family: 'classic',
+    mode: 'dark',
+    dataTheme: 'dark',
+    browserThemeColor: '#020617',
+    statusBarStyle: 'black-translucent',
+    label: 'Классическая тёмная',
+    familyLabel: 'Классическая',
+    modeLabel: 'Тёмная',
+  },
+  {
+    id: 'pink-light',
+    family: 'pink',
+    mode: 'light',
+    dataTheme: 'pink-light',
+    browserThemeColor: '#fff6fb',
+    statusBarStyle: 'default',
+    label: 'Розовая светлая',
+    familyLabel: 'Розовая',
+    modeLabel: 'Светлая',
+  },
+  {
+    id: 'pink-dark',
+    family: 'pink',
+    mode: 'dark',
+    dataTheme: 'pink-dark',
+    browserThemeColor: '#020617',
+    statusBarStyle: 'black-translucent',
+    label: 'Розовая тёмная',
+    familyLabel: 'Розовая',
+    modeLabel: 'Тёмная',
+  },
+  {
+    id: 'green-light',
+    family: 'green',
+    mode: 'light',
+    dataTheme: 'green-light',
+    browserThemeColor: '#f5fbf6',
+    statusBarStyle: 'default',
+    label: 'Зелёная светлая',
+    familyLabel: 'Зелёная',
+    modeLabel: 'Светлая',
+  },
+  {
+    id: 'green-dark',
+    family: 'green',
+    mode: 'dark',
+    dataTheme: 'green-dark',
+    browserThemeColor: '#04120b',
+    statusBarStyle: 'black-translucent',
+    label: 'Зелёная тёмная',
+    familyLabel: 'Зелёная',
+    modeLabel: 'Тёмная',
+  },
+] as const satisfies readonly ThemeVariant[];
+
+const themeVariantMap = new Map<ThemeId, ThemeVariant>(
+  themeVariants.map((variant): [ThemeId, ThemeVariant] => [variant.id, variant]),
+);
+const themeFamilyValues = new Set<string>(themeFamilies);
+const themeModeValues = new Set<string>(themeModes);
+const themePreferenceValues = new Set<string>(themePreferences);
+const themeIdValues = new Set<string>(themeIds);
+
+const THEME_COLOR_META_NAME = 'theme-color';
+const APPLE_STATUS_BAR_META_NAME = 'apple-mobile-web-app-status-bar-style';
+
+/** Имена browser meta, принадлежащих theme document owner. / Browser meta names owned by the theme document contract. */
+export const documentThemeMetaNames = Object.freeze({
+  themeColor: THEME_COLOR_META_NAME,
+  appleStatusBar: APPLE_STATUS_BAR_META_NAME,
+});
+
+export function isThemeFamily(value: unknown): value is ThemeFamily {
+  return typeof value === 'string' && themeFamilyValues.has(value);
+}
+
+export function isThemeMode(value: unknown): value is ThemeMode {
+  return typeof value === 'string' && themeModeValues.has(value);
+}
+
+export function isThemePreference(value: unknown): value is ThemePreference {
+  return typeof value === 'string' && themePreferenceValues.has(value);
+}
+
+export function isThemeId(value: unknown): value is ThemeId {
+  return typeof value === 'string' && themeIdValues.has(value);
+}
+
+export function getThemeVariant(themeId: ThemeId): ThemeVariant {
+  const variant = themeVariantMap.get(themeId);
+  if (variant === undefined) {
+    throw new Error(`Неизвестный идентификатор темы: ${themeId}`);
+  }
+  return variant;
+}
+
+function assertCanonicalThemeVariant(variant: ThemeVariant): ThemeVariant {
+  const canonical = getThemeVariant(variant.id);
+  const fields = [
+    'family',
+    'mode',
+    'dataTheme',
+    'browserThemeColor',
+    'statusBarStyle',
+    'label',
+    'familyLabel',
+    'modeLabel',
+  ] as const satisfies readonly (keyof ThemeVariant)[];
+  const mismatched = fields.filter((field) => variant[field] !== canonical[field]);
+  if (mismatched.length > 0) {
+    throw new Error(
+      `Theme variant "${variant.id}" не совпадает с canonical theme registry: ${mismatched.join(', ')}. `
+      + `Theme variant "${variant.id}" does not match the canonical theme registry: ${mismatched.join(', ')}.`,
+    );
+  }
+  return canonical;
+}
+
+function findDocumentThemeMeta(targetDocument: Document, name: string): HTMLMetaElement | null {
+  const matches = [...targetDocument.head.querySelectorAll<HTMLMetaElement>(`meta[name="${name}"]`)];
+  if (matches.length > 1) {
+    throw new Error(
+      `UI-kit theme document: для "${name}" найдено ${matches.length} meta; ожидается не более одного owner. `
+      + `UI-kit theme document: found ${matches.length} meta elements for "${name}"; at most one owner is allowed.`,
+    );
+  }
+  const existing = matches[0];
+  if (existing === undefined) return null;
+  if (existing.tagName !== 'META') {
+    throw new TypeError(`UI-kit theme document: meta owner "${name}" имеет неверный DOM type.`);
+  }
+  return existing;
+}
+
+function createDocumentThemeMeta(targetDocument: Document, name: string): HTMLMetaElement {
+  const meta = targetDocument.createElement('meta');
+  meta.name = name;
+  meta.dataset.sUiKitThemeMeta = 'true';
+  targetDocument.head.appendChild(meta);
+  return meta;
+}
+
+interface DocumentThemeMetaSnapshot {
+  readonly element: HTMLMetaElement | null;
+  readonly content: string | null;
+}
+
+interface DocumentThemeSnapshot {
+  readonly hadDarkClass: boolean;
+  readonly dataTheme: ThemePreference | null;
+  readonly themeColor: DocumentThemeMetaSnapshot;
+  readonly appleStatusBar: DocumentThemeMetaSnapshot;
+}
+
+interface DocumentThemeScopeLayer {
+  readonly themeId: ThemeId;
+}
+
+interface DocumentThemeScopeRuntime {
+  readonly snapshot: DocumentThemeSnapshot;
+  readonly themeColor: HTMLMetaElement;
+  readonly appleStatusBar: HTMLMetaElement;
+  readonly layers: DocumentThemeScopeLayer[];
+}
+
+const documentThemeScopeRuntimes = new WeakMap<Document, DocumentThemeScopeRuntime>();
+
+function captureDocumentThemeMeta(targetDocument: Document, name: string): DocumentThemeMetaSnapshot {
+  const element = findDocumentThemeMeta(targetDocument, name);
+  return {
+    element,
+    content: element === null ? null : element.getAttribute('content'),
+  };
+}
+
+function captureDocumentTheme(targetDocument: Document): DocumentThemeSnapshot {
+  const hadDarkClass = targetDocument.documentElement.classList.contains('dark');
+  const dataTheme = targetDocument.documentElement.getAttribute('data-theme');
+  if (dataTheme === null && hadDarkClass) {
+    throw new Error('UI-kit theme scope: class="dark" требует canonical data-theme.');
+  }
+  if (dataTheme !== null) {
+    if (!isThemePreference(dataTheme)) {
+      throw new TypeError(`UI-kit theme scope: неизвестный data-theme "${dataTheme}".`);
+    }
+    const variant = themeVariants.find((item) => item.dataTheme === dataTheme);
+    if (variant === undefined || (variant.mode === 'dark') !== hadDarkClass) {
+      throw new Error(`UI-kit theme scope: data-theme="${dataTheme}" конфликтует с class="dark".`);
+    }
+  }
+  return {
+    hadDarkClass,
+    dataTheme,
+    themeColor: captureDocumentThemeMeta(targetDocument, THEME_COLOR_META_NAME),
+    appleStatusBar: captureDocumentThemeMeta(targetDocument, APPLE_STATUS_BAR_META_NAME),
+  };
+}
+
+function assertDocumentThemeMetaRestorable(
+  targetDocument: Document,
+  name: string,
+  snapshot: DocumentThemeMetaSnapshot,
+  appliedElement: HTMLMetaElement,
+): void {
+  const current = findDocumentThemeMeta(targetDocument, name);
+  const expected = snapshot.element === null ? appliedElement : snapshot.element;
+  if (current !== expected) {
+    throw new Error(`UI-kit theme scope: meta owner "${name}" был заменён до восстановления.`);
+  }
+  if (snapshot.element === null && current.dataset.sUiKitThemeMeta !== 'true') {
+    throw new Error(`UI-kit theme scope: meta owner "${name}" изменён вне canonical scope.`);
+  }
+}
+
+function restoreDocumentThemeMeta(
+  snapshot: DocumentThemeMetaSnapshot,
+  appliedElement: HTMLMetaElement,
+): void {
+  if (snapshot.element === null) {
+    appliedElement.remove();
+    return;
+  }
+  if (snapshot.content === null) snapshot.element.removeAttribute('content');
+  else snapshot.element.content = snapshot.content;
+}
+
+function activeDocumentThemeScopeLayer(runtime: DocumentThemeScopeRuntime): DocumentThemeScopeLayer {
+  const layer = runtime.layers[runtime.layers.length - 1];
+  if (layer === undefined) {
+    throw new Error('UI-kit theme scope: runtime не содержит активного owner.');
+  }
+  return layer;
+}
+
+function assertActiveDocumentThemeScope(
+  targetDocument: Document,
+  runtime: DocumentThemeScopeRuntime,
+): void {
+  const variant = getThemeVariant(activeDocumentThemeScopeLayer(runtime).themeId);
+  const root = targetDocument.documentElement;
+  if (root.getAttribute('data-theme') !== variant.dataTheme
+    || root.classList.contains('dark') !== (variant.mode === 'dark')) {
+    throw new Error(
+      `UI-kit theme scope: active owner ${JSON.stringify(variant.id)} был изменён вне canonical scope.`,
+    );
+  }
+  assertDocumentThemeMetaRestorable(
+    targetDocument,
+    THEME_COLOR_META_NAME,
+    runtime.snapshot.themeColor,
+    runtime.themeColor,
+  );
+  assertDocumentThemeMetaRestorable(
+    targetDocument,
+    APPLE_STATUS_BAR_META_NAME,
+    runtime.snapshot.appleStatusBar,
+    runtime.appleStatusBar,
+  );
+  if (runtime.themeColor.content !== variant.browserThemeColor
+    || runtime.appleStatusBar.content !== variant.statusBarStyle) {
+    throw new Error(
+      `UI-kit theme scope: browser meta active owner ${JSON.stringify(variant.id)} изменены вне canonical scope.`,
+    );
+  }
+}
+
+function restoreDocumentThemeScope(
+  targetDocument: Document,
+  runtime: DocumentThemeScopeRuntime,
+): void {
+  const snapshot = runtime.snapshot;
+  targetDocument.documentElement.classList.toggle('dark', snapshot.hadDarkClass);
+  if (snapshot.dataTheme === null) targetDocument.documentElement.removeAttribute('data-theme');
+  else targetDocument.documentElement.setAttribute('data-theme', snapshot.dataTheme);
+  restoreDocumentThemeMeta(snapshot.themeColor, runtime.themeColor);
+  restoreDocumentThemeMeta(snapshot.appleStatusBar, runtime.appleStatusBar);
+  documentThemeScopeRuntimes.delete(targetDocument);
+}
+
+/**
+ * Атомарно применяет canonical theme variant к class, data-theme и browser meta одного документа.
+ * Atomically applies a canonical theme variant to one document's class, data-theme, and browser meta contract.
+ */
+export function applyThemeVariantToDocument(targetDocument: Document, candidate: ThemeVariant): void {
+  const variant = assertCanonicalThemeVariant(candidate);
+  const themeColorMeta = findDocumentThemeMeta(targetDocument, THEME_COLOR_META_NAME);
+  const statusBarMeta = findDocumentThemeMeta(targetDocument, APPLE_STATUS_BAR_META_NAME);
+  const resolvedThemeColorMeta = themeColorMeta === null
+    ? createDocumentThemeMeta(targetDocument, THEME_COLOR_META_NAME)
+    : themeColorMeta;
+  const resolvedStatusBarMeta = statusBarMeta === null
+    ? createDocumentThemeMeta(targetDocument, APPLE_STATUS_BAR_META_NAME)
+    : statusBarMeta;
+
+  targetDocument.documentElement.classList.toggle('dark', variant.mode === 'dark');
+  targetDocument.documentElement.dataset.theme = variant.dataTheme;
+  resolvedThemeColorMeta.content = variant.browserThemeColor;
+  resolvedStatusBarMeta.content = variant.statusBarStyle;
+}
+
+/**
+ * Применяет зарегистрированный ThemeId через единственного document owner.
+ * Applies a registered ThemeId through the single document owner.
+ */
+export function applyThemeIdToDocument(targetDocument: Document, themeId: ThemeId): void {
+  applyThemeVariantToDocument(targetDocument, getThemeVariant(themeId));
+}
+
+/**
+ * Временно применяет canonical тему и возвращает идемпотентное точное восстановление document state.
+ * Temporarily applies a canonical theme and returns an idempotent exact document-state restore.
+ */
+export function applyScopedThemeIdToDocument(targetDocument: Document, themeId: ThemeId): () => void {
+  const variant = getThemeVariant(themeId);
+  let runtime = documentThemeScopeRuntimes.get(targetDocument);
+  if (runtime !== undefined) assertActiveDocumentThemeScope(targetDocument, runtime);
+  const snapshot = runtime === undefined ? captureDocumentTheme(targetDocument) : runtime.snapshot;
+  applyThemeIdToDocument(targetDocument, themeId);
+  const appliedThemeColor = findDocumentThemeMeta(targetDocument, THEME_COLOR_META_NAME);
+  const appliedAppleStatusBar = findDocumentThemeMeta(targetDocument, APPLE_STATUS_BAR_META_NAME);
+  if (appliedThemeColor === null || appliedAppleStatusBar === null) {
+    throw new Error('UI-kit theme scope: canonical applier не создал обязательные browser meta owners.');
+  }
+  if (runtime === undefined) {
+    runtime = {
+      snapshot,
+      themeColor: appliedThemeColor,
+      appleStatusBar: appliedAppleStatusBar,
+      layers: [],
+    };
+    documentThemeScopeRuntimes.set(targetDocument, runtime);
+  } else if (runtime.themeColor !== appliedThemeColor || runtime.appleStatusBar !== appliedAppleStatusBar) {
+    throw new Error('UI-kit theme scope: canonical browser meta owners были заменены при apply.');
+  }
+  const layer: DocumentThemeScopeLayer = { themeId: variant.id };
+  runtime.layers.push(layer);
+  let active = true;
+  return () => {
+    if (!active) return;
+    const currentRuntime = documentThemeScopeRuntimes.get(targetDocument);
+    if (currentRuntime !== runtime) {
+      throw new Error('UI-kit theme scope: per-document runtime был заменён до cleanup.');
+    }
+    assertActiveDocumentThemeScope(targetDocument, currentRuntime);
+    const layerIndex = currentRuntime.layers.indexOf(layer);
+    if (layerIndex < 0) {
+      throw new Error('UI-kit theme scope: active owner отсутствует в per-document runtime.');
+    }
+    currentRuntime.layers.splice(layerIndex, 1);
+    if (currentRuntime.layers.length === 0) restoreDocumentThemeScope(targetDocument, currentRuntime);
+    else applyThemeIdToDocument(targetDocument, activeDocumentThemeScopeLayer(currentRuntime).themeId);
+    active = false;
+  };
+}
+
+export function getThemeVariantsForFamily(family: ThemeFamily): ThemeVariant[] {
+  return themeVariants.filter((variant) => variant.family === family);
+}
+
+export function getThemeModesForFamily(family: ThemeFamily): ThemeMode[] {
+  return getThemeVariantsForFamily(family).map((variant) => variant.mode);
+}
+
+export function resolveThemeId(
+  family: ThemeFamily,
+  mode: ThemeMode,
+): ThemeId | null {
+  const match = themeVariants.find((variant) => variant.family === family && variant.mode === mode);
+  return match === undefined ? null : match.id;
+}
+
+export function resolveThemePreference(themeId: ThemeId): ThemePreference {
+  return getThemeVariant(themeId).dataTheme;
+}
+
+export function getThemeFamilyLabel(family: ThemeFamily): string {
+  const variant = themeVariants.find((item) => item.family === family);
+  if (variant === undefined) {
+    throw new Error(`Неизвестное семейство темы: ${family}`);
+  }
+  return variant.familyLabel;
+}
+
+export function getThemeModeLabel(mode: ThemeMode): string {
+  if (mode === 'light') {
+    return 'Светлая';
+  }
+  if (mode === 'dark') {
+    return 'Тёмная';
+  }
+  throw new Error(`Неизвестный режим темы: ${String(mode)}`);
+}
+
+export function resolveLegacyThemeId(value: unknown): ThemeId | null {
+  if (value === 'light') {
+    return 'classic-light';
+  }
+  if (value === 'dark') {
+    return 'classic-dark';
+  }
+  if (value === 'pink-dark') {
+    return 'pink-dark';
+  }
+  return null;
+}

package/src/types/highlight-js-lib.d.ts

@@ -0,0 +1,76 @@
+declare module 'highlight.js/lib/core' {
+  import type { HLJSApi } from 'highlight.js';
+
+  const hljs: HLJSApi;
+  export default hljs;
+}
+
+declare module 'highlight.js/lib/languages/bash' {
+  import type { LanguageFn } from 'highlight.js';
+
+  const language: LanguageFn;
+  export default language;
+}
+
+declare module 'highlight.js/lib/languages/dockerfile' {
+  import type { LanguageFn } from 'highlight.js';
+
+  const language: LanguageFn;
+  export default language;
+}
+
+declare module 'highlight.js/lib/languages/javascript' {
+  import type { LanguageFn } from 'highlight.js';
+
+  const language: LanguageFn;
+  export default language;
+}
+
+declare module 'highlight.js/lib/languages/makefile' {
+  import type { LanguageFn } from 'highlight.js';
+
+  const language: LanguageFn;
+  export default language;
+}
+
+declare module 'highlight.js/lib/languages/nginx' {
+  import type { LanguageFn } from 'highlight.js';
+
+  const language: LanguageFn;
+  export default language;
+}
+
+declare module 'highlight.js/lib/languages/powershell' {
+  import type { LanguageFn } from 'highlight.js';
+
+  const language: LanguageFn;
+  export default language;
+}
+
+declare module 'highlight.js/lib/languages/python' {
+  import type { LanguageFn } from 'highlight.js';
+
+  const language: LanguageFn;
+  export default language;
+}
+
+declare module 'highlight.js/lib/languages/typescript' {
+  import type { LanguageFn } from 'highlight.js';
+
+  const language: LanguageFn;
+  export default language;
+}
+
+declare module 'highlight.js/lib/languages/xml' {
+  import type { LanguageFn } from 'highlight.js';
+
+  const language: LanguageFn;
+  export default language;
+}
+
+declare module 'highlight.js/lib/languages/yaml' {
+  import type { LanguageFn } from 'highlight.js';
+
+  const language: LanguageFn;
+  export default language;
+}

package/src/variants.ts

@@ -0,0 +1,15 @@
+export const toneVariants = [
+  'primary',
+  'secondary',
+  'success',
+  'info',
+  'warn',
+  'danger',
+  'contrast',
+  'neutral',
+] as const;
+
+export type ToneVariant = (typeof toneVariants)[number];
+
+export const sizeVariants = ['sm', 'md', 'lg'] as const;
+export type SizeVariant = (typeof sizeVariants)[number];