Справочник

Типы TypeScript

Все публичные типы экспортируются из корня пакета:

import type {
  ColorType, // 'hex' | 'css-var' | 'rgb' | 'hsl' | 'named' | 'oklch' | 'color' | 'unknown'
  WcagLevel, // 'AAA' | 'AA' | 'AA-large' | 'fail'
  ColorBlindnessType, // 'protanopia' | 'deuteranopia' | 'tritanopia'
  BackgroundSpec, // string | { type: 'semi-transparent'; ... } | { type: 'gradient'; ... }
  PaletteScore, // { palette, minContrastRatio, avgContrastRatio }
} from 'color-value-tools'

BackgroundSpec — дискриминированное объединение

import type { BackgroundSpec } from 'color-value-tools'

const solid: BackgroundSpec = '#3498db'

const semiTransparent: BackgroundSpec = {
  type: 'semi-transparent',
  color: 'rgba(0,0,0,0.4)',
  underlay: '#ffffff', // опционально, по умолчанию белый
}

const gradient: BackgroundSpec = {
  type: 'gradient',
  stops: ['#1a1a2e', '#e94560', '#f5a623'],
}

PaletteScore — результат bestContrastPalette

import type { PaletteScore } from 'color-value-tools'

const result: PaletteScore & { paletteIndex: number } = bestContrastPalette(bg, palettes)
result.paletteIndex // number
result.palette // string[]
result.minContrastRatio // number
result.avgContrastRatio // number

Вывод типов из normalizeColor

import { normalizeColor } from 'color-value-tools'

const n = normalizeColor('#3498db')
// TypeScript знает: n.hex, n.r, n.g, n.b, n.h, n.s, n.l, n.v, n.a, n.type

if (n.type !== 'unknown' && n.type !== 'css-var') {
  const r: number = n.r! // доступно для всех разрешённых типов цвета
}

Архитектура

color-value-tools
│
├── Определение (Detection)
│     getColorType, isHexColor, isRgbColor, isHslColor,
│     isOklchColor, isColorFunction, isCssVariable
│
├── Парсинг (Parsing)
│     normalizeColor          → универсальная точка входа; обрабатывает все форматы + объекты
│     rgbaStringToRgba        → парсер rgb()/rgba()
│     hex8ToRgba              → 8-значный и 4-значный hex с альфой
│     parseOklchString        → oklch(L C H / alpha) с поддержкой % L
│     parseColorFn            → color(display-p3 ...) / color(srgb ...)
│     parseHwbString          → строка hwb()
│     parseCssVar             → var(--name, fallback)
│
├── Цветовая математика — каждое пространство через RGB как хаб
│     sRGB ↔ Linear (srgbChanToLinear / linearChanToSrgb)
│     промежуточный XYZ D65 для Lab/LCH
│     Oklab/Oklch — матрицы Бьорна Оттоссона
│     Display P3 — матрицы ICC sRGB→P3 и P3→sRGB
│
├── Манипуляции (Manipulation)
│     lighten / darken / saturate / desaturate — через HSL
│     invertColor — инверсия RGB
│     grayscale — перцептивные веса BT.709
│     rotateHue — сдвиг оттенка через HSL
│     adjustHexBrightness — линейное смешивание канала к 0/255
│     setAlpha / getAlpha — работа со строкой rgba
│
├── mixColors  (ядро системы интерполяции)
│     6 режимов цветового пространства: rgb | hsl | lab | lch | oklab | oklch
│     4 режима интерполяции оттенка: shorter | longer | increasing | decreasing
│     4 формата вывода: hex | rgb | rgba | hsl
│     Используется внутри: interpolateColors, createColorScale,
│       midpointColor, tints, shades, tones,
│       generateGradientColors*, generateTints*, generateShades*
│
├── Цветовые гармонии
│     Все реализованы как повороты оттенка на нормализованном hex
│
├── Генерация палитр
│     colorShades — развёртка светлоты HSL
│     monochromatic — развёртка насыщенности HSL
│     tints / shades / tones — интерполяция в Oklab через mixColors
│
├── Доступность
│     relativeLuminance — формула линеаризации WCAG
│     contrastRatio — (L1+0.05)/(L2+0.05)
│     wcagLevel — пороги коэффициента 3 / 4.5 / 7
│     isReadableOnBackground — обрабатывает 3 типа фона;
│       semi-transparent: альфа-композитинг поверх подложки перед проверкой коэффициента
│       gradient: оценивает каждую точку, использует минимальный коэффициент
│     bestContrastPalette — оценка = avg×0.4 + min×0.6
│
├── Дальтонизм
│     Матрицы Vienot 1999 на линейном RGB
│     3 типа: protanopia / deuteranopia / tritanopia
│
├── Кэш
│     Простая Map<string, NormalizeResult>
│     normalizeColorCached — поиск в Map перед вызовом normalizeColor
│     getCacheStats / clearColorCache / enableCache / disableCache
│
├── Функции-генераторы
│     Синтаксис генераторов ES2015 (*) — возвращает по одному цвету за раз
│     generateGradientColors* → mixColors внутри генератора
│     generateTints* / generateShades* → смешивание в Oklab к белому/чёрному
│
└── CLI (dist/cli/cli.js → cvt)
      Команды: info | convert | contrast | shades | harmonies | nearest
      Принимает любой формат цвета, понятный normalizeColor
      Импортирует собранный пакет — без отдельной копии библиотеки

Модули

Исходный код разбит на модули, и каждый из них также доступен как импорт по подпути:

Модуль	Подпуть	Содержимое
parse	color-value-tools/parse	Определение типа, парсеры CSS-строк, normalizeColor, имена цветов
convert	color-value-tools/convert	Конвертации между цветовыми пространствами, форматтеры CSS-строк
manipulate	color-value-tools/manipulate	Светлота, насыщенность, альфа, rotateHue, mixColors
palette	color-value-tools/palette	Гармонии, шкалы, tints/shades/tones, генераторы, randomColor
a11y	color-value-tools/a11y	Яркость, контраст, WCAG, colorDeltaE, дальтонизм
cache	color-value-tools/cache	normalizeColorCached и управление кэшем

Корень пакета color-value-tools реэкспортирует их все.

Размер бандла и зависимости

Node.js	>=18
Runtime-зависимости	Нет
Peer-зависимости	Нет
Dev-зависимости	TypeScript, Vitest, Prettier
ESM точка входа	dist/esm/index.js (tree-shakeable)
CJS точка входа	dist/cjs/index.js
Типы	.d.ts для ESM- и CJS-сборки
CLI точка входа	dist/cli/cli.js → cvt

Пакет поставляется и как ESM, и как CommonJS: сам пакет — CommonJS, а ESM-сборка лежит в dist/esm со своим type: module. Каждая функция — именованный экспорт, а пакет помечен как sideEffects: false, поэтому бандлеры с поддержкой tree-shaking удаляют неиспользуемые функции.

Лицензия

MIT