@cloud-ru/ds-theme 1.0.0

package/src/utils/customTheme/color/conversions.ts

@@ -0,0 +1,113 @@
+// Матрицы и формулы преобразований цветовых пространств — из CSS Color 4
+// (https://drafts.csswg.org/css-color-4/conversions.js) и работы Björn Ottosson по OKLab
+// (https://bottosson.github.io/posts/oklab/). Константы менять нельзя; тип-контракт 3×3-матрицы
+// фиксирован, чтобы обойтись без `any`/`@ts-ignore` в обобщённом умножении.
+
+import { LAB, LCH, Mat3, RGB, Vec3, XYZ } from './types';
+
+/** Умножение матрицы 3×3 на вектор из трёх компонентов. */
+function mulV(m: Mat3, v: Vec3): Vec3 {
+  return [
+    m[0][0] * v[0] + m[0][1] * v[1] + m[0][2] * v[2],
+    m[1][0] * v[0] + m[1][1] * v[1] + m[1][2] * v[2],
+    m[2][0] * v[0] + m[2][1] * v[1] + m[2][2] * v[2],
+  ];
+}
+
+const XYZ_TO_LMS: Mat3 = [
+  [0.8190224432164319, 0.3619062562801221, -0.12887378261216414],
+  [0.0329836671980271, 0.9292868468965546, 0.03614466816999844],
+  [0.048177199566046255, 0.26423952494422764, 0.6335478258136937],
+];
+
+const LMS_TO_OKLAB: Mat3 = [
+  [0.2104542553, 0.793617785, -0.0040720468],
+  [1.9779984951, -2.428592205, 0.4505937099],
+  [0.0259040371, 0.7827717662, -0.808675766],
+];
+
+const LMS_TO_XYZ: Mat3 = [
+  [1.2268798733741557, -0.5578149965554813, 0.28139105017721583],
+  [-0.04057576262431372, 1.1122868293970594, -0.07171106666151701],
+  [-0.07637294974672142, -0.4214933239627914, 1.5869240244272418],
+];
+
+// prettier-ignore
+const OKLAB_TO_LMS: Mat3 = [
+  // eslint-disable-next-line no-loss-of-precision
+  [0.99999999845051981432, 0.39633779217376785678, 0.21580375806075880339],
+  // eslint-disable-next-line no-loss-of-precision
+  [1.0000000088817607767, -0.1055613423236563494, -0.063854174771705903402],
+  // eslint-disable-next-line no-loss-of-precision
+  [1.0000000546724109177, -0.089484182094965759684, -1.2914855378640917399],
+];
+
+const LIN_SRGB_TO_XYZ: Mat3 = [
+  [0.41239079926595934, 0.357584339383878, 0.1804807884018343],
+  [0.21263900587151027, 0.715168678767756, 0.07219231536073371],
+  [0.01933081871559182, 0.11919477979462598, 0.9505321522496607],
+];
+
+const XYZ_TO_LIN_SRGB: Mat3 = [
+  [3.2409699419045226, -1.537383177570094, -0.4986107602930034],
+  [-0.9692436362808796, 1.8759675015077202, 0.04155505740717559],
+  [0.05563007969699366, -0.20397695888897652, 1.0569715142428786],
+];
+
+/** XYZ (относительно D65) → OKLab. `L` в диапазоне `[0,1]`. */
+export function xyzToOklab(xyz: XYZ): LAB {
+  const lms = mulV(XYZ_TO_LMS, xyz);
+  const lmsCbrt: Vec3 = [Math.cbrt(lms[0]), Math.cbrt(lms[1]), Math.cbrt(lms[2])];
+
+  return mulV(LMS_TO_OKLAB, lmsCbrt);
+}
+
+/** OKLab → XYZ (относительно D65). */
+export function oklabToXyz(lab: LAB): XYZ {
+  const lms = mulV(OKLAB_TO_LMS, lab);
+  const lmsCubed: Vec3 = [lms[0] ** 3, lms[1] ** 3, lms[2] ** 3];
+
+  return mulV(LMS_TO_XYZ, lmsCubed);
+}
+
+/** OKLab → OKLCH. Hue возвращается в градусах `[0,360)`. */
+export function oklabToOklch(lab: LAB): LCH {
+  const hue = (Math.atan2(lab[2], lab[1]) * 180) / Math.PI;
+
+  return [lab[0], Math.sqrt(lab[1] ** 2 + lab[2] ** 2), hue >= 0 ? hue : hue + 360];
+}
+
+/** OKLCH → OKLab. */
+export function oklchToOklab(lch: LCH): LAB {
+  return [lch[0], lch[1] * Math.cos((lch[2] * Math.PI) / 180), lch[1] * Math.sin((lch[2] * Math.PI) / 180)];
+}
+
+/** sRGB → linear-light sRGB (обратная gamma-коррекция), расширенная функция для отрицательных значений. */
+export function linSRGB(rgb: RGB): RGB {
+  return rgb.map(val => {
+    const sign = val < 0 ? -1 : 1;
+    const abs = Math.abs(val);
+
+    return abs < 0.04045 ? val / 12.92 : sign * Math.pow((abs + 0.055) / 1.055, 2.4);
+  }) as RGB;
+}
+
+/** linear-light sRGB → sRGB (gamma-коррекция), расширенная функция для отрицательных значений. */
+export function gamSRGB(rgb: RGB): RGB {
+  return rgb.map(val => {
+    const sign = val < 0 ? -1 : 1;
+    const abs = Math.abs(val);
+
+    return abs > 0.0031308 ? sign * (1.055 * Math.pow(abs, 1 / 2.4) - 0.055) : 12.92 * val;
+  }) as RGB;
+}
+
+/** linear-light sRGB → CIE XYZ (белая точка D65). */
+export function linSRGBToXYZ(rgb: RGB): XYZ {
+  return mulV(LIN_SRGB_TO_XYZ, rgb);
+}
+
+/** CIE XYZ → linear-light sRGB. */
+export function xyzToLinSRGB(xyz: XYZ): RGB {
+  return mulV(XYZ_TO_LIN_SRGB, xyz);
+}

package/src/utils/customTheme/color/hex.ts

@@ -0,0 +1,39 @@
+import { RGB } from './types';
+
+const SHORT_HEX = /^#?([\da-f])([\da-f])([\da-f])([\da-f])?$/i;
+const LONG_HEX = /^#?([\da-f]{2})([\da-f]{2})([\da-f]{2})([\da-f]{2})?$/i;
+
+/**
+ * Разбирает hex-строку в sRGB-каналы `[r, g, b]` в диапазоне 0–255. Поддерживает `#rgb`, `#rgba`,
+ * `#rrggbb`, `#rrggbbaa` (с ведущим `#` и без). Alpha-канал игнорируется. Невалидная строка → `null`.
+ */
+export function parseHex(hex: string): RGB | null {
+  const trimmed = hex.trim();
+
+  const short = SHORT_HEX.exec(trimmed);
+  if (short) {
+    return [parseInt(short[1] + short[1], 16), parseInt(short[2] + short[2], 16), parseInt(short[3] + short[3], 16)];
+  }
+
+  const long = LONG_HEX.exec(trimmed);
+  if (long) {
+    return [parseInt(long[1], 16), parseInt(long[2], 16), parseInt(long[3], 16)];
+  }
+
+  return null;
+}
+
+/** Проверяет, что строка — валидный hex-цвет (`#rgb` / `#rgba` / `#rrggbb` / `#rrggbbaa`). */
+export function isValidHex(hex: string): boolean {
+  return parseHex(hex) !== null;
+}
+
+/** sRGB-каналы 0–1 → hex-строка `#rrggbb`. Каналы клампятся в диапазон. */
+export function srgbToHex([r, g, b]: RGB): string {
+  const toHex = (channel: number): string =>
+    Math.round(Math.min(255, Math.max(0, channel * 255)))
+      .toString(16)
+      .padStart(2, '0');
+
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}

package/src/utils/customTheme/color/index.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './hex';
+export * from './colorSpace';
+export * from './apca';

package/src/utils/customTheme/color/oklch.ts

@@ -0,0 +1,22 @@
+import { oklabToOklch, oklabToXyz, oklchToOklab, xyzToOklab } from './conversions';
+import { LCH, TLchModel, XYZ } from './types';
+
+// L компонента OKLCH хранится наружу в процентах [0–100], внутри модели — в [0–1].
+function toDisplayOKLCH([l, c, h]: LCH): LCH {
+  return [l * 100, c, h];
+}
+
+function fromDisplayOKLCH([l, c, h]: LCH): LCH {
+  return [l / 100, c, h];
+}
+
+/** Модель OKLCH: перевод LCH↔XYZ через OKLab. `L` наружу — в процентах. */
+export const oklch: TLchModel = {
+  lch2xyz: (lch: LCH): XYZ => oklabToXyz(oklchToOklab(fromDisplayOKLCH(lch))),
+  xyz2lch: (xyz: XYZ): LCH => toDisplayOKLCH(oklabToOklch(xyzToOklab(xyz))),
+  ranges: {
+    l: { min: 0, max: 100, step: 0.5 },
+    c: { min: 0, max: 0.33, step: 0.005 },
+    h: { min: 0, max: 360, step: 0.5 },
+  },
+};

package/src/utils/customTheme/color/types.ts

@@ -0,0 +1,32 @@
+/** Вектор из трёх чисел — канал цвета в любом из пространств (RGB/XYZ/LAB/LCH). */
+export type Vec3 = [number, number, number];
+
+/** Матрица 3×3 для линейных преобразований цветовых пространств. */
+export type Mat3 = [Vec3, Vec3, Vec3];
+
+export type XYZ = Vec3;
+export type LAB = Vec3;
+export type LCH = Vec3;
+export type RGB = Vec3;
+
+/** Разобранный цвет: OKLCH-компоненты (`l`,`c`,`h`), sRGB-каналы 0–255 (`r`,`g`,`b`) и hex. */
+export type TColor = {
+  l: number;
+  c: number;
+  h: number;
+  r: number;
+  g: number;
+  b: number;
+  hex: string;
+};
+
+/** Модель цветового пространства LCH: конвертеры в/из XYZ и диапазоны компонентов. */
+export type TLchModel = {
+  ranges: {
+    l: { min: number; max: number; step: number };
+    c: { min: number; max: number; step: number };
+    h: { min: number; max: number; step: number };
+  };
+  xyz2lch(xyz: XYZ): LCH;
+  lch2xyz(lch: LCH): XYZ;
+};

package/src/utils/customTheme/constants.ts

@@ -0,0 +1,57 @@
+// Опорная палитра и тон-константы для генерации кастомного бренд-цвета. Тоновый набор и дефолтные
+// hex совпадают с `--sn-brand-color-primary-<tone>` бренда `brandA` из `@cloud-ru/figma-variables`:
+// генератор держит `L`/`C` этих тонов и поворачивает hue к seed-цвету потребителя.
+
+/** Тон акцента (`--sn-brand-color-primary-55`) — им становится сам seed-цвет. */
+export const PRIMARY_ACCENT_TONE = '55';
+
+/** Near-white тон для текста на акценте (совпадает с дефолтом `onAccentLight` бренда `brandA`). */
+export const NEAR_WHITE_TONE = '99';
+
+/** Near-dark тон для текста на акценте (совпадает с дефолтом `onAccentDark` бренда `brandA`). */
+export const NEAR_DARK_TONE = '5';
+
+/** Все числовые тоны палитры `--sn-brand-color-primary-<tone>`. */
+export const BRAND_PRIMARY_TONES = ['5', '10', '15', '25', '45', '55', '60', '65', '80', '90', '95', '99'] as const;
+
+export type BrandPrimaryTone = (typeof BRAND_PRIMARY_TONES)[number];
+
+/** Опорные hex тонов бренда `brandA` — источник `L`/`C` для генерации по любому seed-цвету. */
+export const BASE_BRAND_PALETTE: Record<BrandPrimaryTone, string> = {
+  '5': '#21372f',
+  '10': '#243e35',
+  '15': '#2b483c',
+  '25': '#2c5e49',
+  '45': '#22775b',
+  '55': '#389f74',
+  '60': '#5ebb91',
+  '65': '#85ceaa',
+  '80': '#caeadb',
+  '90': '#edf7f1',
+  '95': '#f5fdf8',
+  '99': '#fbfffc',
+};
+
+/** Префикс CSS-переменных бренд-палитры. */
+export const BRAND_PRIMARY_VAR_PREFIX = '--sn-brand-color-primary-';
+
+/** Alpha-суффикс для `--sn-brand-color-primary-transparent` (совпадает с дефолтом `#389f7424` бренда `brandA`). */
+export const TRANSPARENT_ALPHA_SUFFIX = '24';
+
+/**
+ * Тинты акцента для activated-состояний (`--sn-brand-color-state-activated-*-background`) — это
+ * акцентный тон с alpha. Суффиксы совпадают с дефолтами brandA (`#389f7426/59/73`). Без них
+ * activated-заливки (выбранная строка таблицы, active-состояния) не следуют за кастомным бренд-цветом.
+ */
+export const ACTIVATED_ALPHA_SUFFIX = {
+  default: '26',
+  hovered: '59',
+  pressed: '73',
+} as const;
+
+/** Имена CSS-переменных activated-заливок. */
+export const BRAND_ACTIVATED_VAR = {
+  default: '--sn-brand-color-state-activated-default-background',
+  hovered: '--sn-brand-color-state-activated-hovered-background',
+  pressed: '--sn-brand-color-state-activated-pressed-background',
+} as const;

package/src/utils/customTheme/generateBrandPalette.ts

@@ -0,0 +1,30 @@
+import { hex2color, lch2color } from './color';
+import { BASE_BRAND_PALETTE, BRAND_PRIMARY_TONES, BrandPrimaryTone, PRIMARY_ACCENT_TONE } from './constants';
+
+/** Сгенерированная бренд-палитра: тон → hex. */
+export type BrandPalette = Record<BrandPrimaryTone, string>;
+
+/**
+ * Строит бренд-палитру из одного seed-цвета: берёт `L`/`C` каждого опорного тона `BASE_BRAND_PALETTE`
+ * и поворачивает hue к hue seed-цвета (OKLCH). Тон акцента (`55`) становится самим seed-цветом.
+ * Так один цвет потребителя перекрашивает всю шкалу `--sn-brand-color-primary-<tone>`, сохраняя
+ * светлоту/насыщенность DS-палитры. Невалидный hex → `null`.
+ */
+export function generateBrandPalette(seedColor: string): BrandPalette | null {
+  const seed = hex2color(seedColor);
+  if (!seed) {
+    return null;
+  }
+
+  const { h: hue } = seed;
+  const palette = {} as BrandPalette;
+
+  for (const tone of BRAND_PRIMARY_TONES) {
+    const baseHex = tone === PRIMARY_ACCENT_TONE ? seedColor : BASE_BRAND_PALETTE[tone];
+    const base = hex2color(baseHex);
+
+    palette[tone] = base ? lch2color([base.l, base.c, hue]).hex : baseHex;
+  }
+
+  return palette;
+}

package/src/utils/customTheme/index.ts

@@ -0,0 +1,4 @@
+export * from './constants';
+export * from './generateBrandPalette';
+export * from './buildBrandPaletteVars';
+export * from './buildBrandPaletteCss';

package/src/utils/getThemeClassnames.ts

@@ -0,0 +1,40 @@
+import { ThemeAppearance } from '../types/appearance';
+
+/**
+ * Чистая функция: собирает **полный** набор `sn-*` классов из осей оформления списком токенов.
+ * Полный набор обязателен на каждой DOM-границе — токены `@cloud-ru/figma-variables` не
+ * переопределяются по одной оси через CSS-каскад (см. providers-standard.md). Базовые слои
+ * (`sn-base-styles`, `sn-figmaStyles`, `sn-components`) и материал (`sn-yes`/`sn-no`)
+ * — всегда; `density`/`colorScheme`/`brand`/`brandRole` — если заданы.
+ *
+ * Списочная форма — источник истины для `getThemeClassnames` (строка через `join`) и для
+ * `element.classList.add(...)`, которому нужны отдельные токены без промежуточного `split`.
+ */
+export function getThemeClassnameList(appearance: ThemeAppearance = {}): string[] {
+  const { density, colorScheme, brand, brandRole, acrylic } = appearance;
+
+  const classes = ['sn-base-styles', 'sn-figmaStyles', 'sn-components', acrylic ? 'sn-yes' : 'sn-no'];
+
+  if (density) {
+    classes.push(`sn-${density}`);
+  }
+  if (colorScheme) {
+    classes.push(`sn-${colorScheme}`);
+  }
+  if (brand) {
+    classes.push(`sn-${brand}`);
+  }
+  if (brandRole) {
+    classes.push(`sn-${brandRole}`);
+  }
+
+  return classes;
+}
+
+/**
+ * Строковая форма набора `sn-*` (через `join`). Используется на SSR (строка класса на `<html>`) и
+ * как основа хука `useThemeClassnames`. Для `classList`-операций бери `getThemeClassnameList`.
+ */
+export function getThemeClassnames(appearance: ThemeAppearance = {}): string {
+  return getThemeClassnameList(appearance).join(' ');
+}

package/src/utils/index.ts

@@ -0,0 +1,7 @@
+export * from './mergeAppearance';
+export * from './getThemeClassnames';
+export * from './resolveColorScheme';
+export * from './colorSchemeStorage';
+export * from './colorSchemeFromHeaders';
+export * from './themeBootstrap';
+export * from './customTheme';

package/src/utils/mergeAppearance.ts

@@ -0,0 +1,16 @@
+import { ThemeAppearance } from '../types/appearance';
+
+/**
+ * Сливает оформление родителя с переопределениями: незаданные (`undefined`) оси `overrides` НЕ
+ * затирают унаследованные (`??` сохраняет, в т.ч. `acrylic: false`). Используется `ChildThemeProvider`
+ * для Figma-цепочки модификаторов.
+ */
+export function mergeAppearance(parent: ThemeAppearance, overrides: Partial<ThemeAppearance>): ThemeAppearance {
+  return {
+    colorScheme: overrides.colorScheme ?? parent.colorScheme,
+    brand: overrides.brand ?? parent.brand,
+    brandRole: overrides.brandRole ?? parent.brandRole,
+    density: overrides.density ?? parent.density,
+    acrylic: overrides.acrylic ?? parent.acrylic,
+  };
+}

package/src/utils/resolveColorScheme.ts

@@ -0,0 +1,15 @@
+import { COLOR_SCHEME, THEME_OVERRIDE } from '../constants/colorScheme';
+import { ColorScheme, ThemeOverride } from '../types/colorScheme';
+
+/**
+ * Резолв итоговой схемы: явный override (`light`/`dark`) побеждает; `system`/отсутствие — по
+ * системному `prefers-color-scheme` (`systemPrefersDark`). Поэтому «всегда светлая» остаётся
+ * светлой даже на тёмном устройстве.
+ */
+export function resolveColorScheme(override: ThemeOverride | undefined, systemPrefersDark: boolean): ColorScheme {
+  if (override === THEME_OVERRIDE.Light || override === THEME_OVERRIDE.Dark) {
+    return override;
+  }
+
+  return systemPrefersDark ? COLOR_SCHEME.Dark : COLOR_SCHEME.Light;
+}

package/src/utils/themeBootstrap.ts

@@ -0,0 +1,18 @@
+import { THEME_OVERRIDE_STORAGE_KEY } from '../constants/colorScheme';
+
+/**
+ * Возвращает строку синхронного inline-скрипта для `<head>` (до `<body>`): читает override из
+ * cookie + `prefers-color-scheme` и ставит `sn-light`/`sn-dark` на корень ДО первой отрисовки —
+ * устраняет «моргание» темы при перезагрузке. Вставляется через `<script dangerouslySetInnerHTML>`
+ * (Next) или статическим `<script>` в `<head>` (single-spa). Читает ту же cookie, что и SSR.
+ *
+ * `target` — CSS-селектор корня; по умолчанию `<html>` (`document.documentElement`).
+ */
+export function getThemeBootstrapScript(options?: { storageKey?: string; target?: string }): string {
+  const storageKey = JSON.stringify(options?.storageKey ?? THEME_OVERRIDE_STORAGE_KEY);
+  const target = options?.target
+    ? `document.querySelector(${JSON.stringify(options.target)})`
+    : 'document.documentElement';
+
+  return `(function(){try{var k=${storageKey},m=document.cookie.match(new RegExp('(?:^|; )'+k+'=([^;]*)')),o=m?decodeURIComponent(m[1]):null,d=(o==='dark')||((o==='system'||!o)&&matchMedia('(prefers-color-scheme: dark)').matches),el=${target};if(el){el.classList.toggle('sn-dark',d);el.classList.toggle('sn-light',!d);}}catch(e){}})();`;
+}