Справочник

Типы TypeScript

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

import type {
  // Цветовая точка
  ColorStop,

  // Линейный градиент
  GradientOptions,
  GradientDirection,
  ColorInterpolation,
  ScaleInterpolation,

  // Радиальный градиент
  RadialGradientOptions,
  RadialGradientLayer,
  RadialHarmonyType,

  // Конический градиент
  ConicGradientOptions,

  // Генераторы гармоний
  HarmonyGradientOptions,

  // Доступность
  AccessibleGradientOptions,
  GradientWcagReport,
  WcagLevel,

  // Экспорт в canvas
  CanvasGradientParams,
  CanvasLinearGradientParams,
  CanvasRadialGradientParams,
  CanvasConicGradientParams,
} from 'css-magic-gradient'

Значения WcagLevel:

type WcagLevel = 'AAA' | 'AA' | 'AA-large' | 'fail'

Значения ColorInterpolation (CSS Color Level 4 — передаётся браузеру как in <space> в строке градиента):

type ColorInterpolation = 'srgb' | 'oklch' | 'lab' | 'hsl' | 'oklab' | 'lch'

Значения ScaleInterpolation (JS-смешивание цветов для генераторов гармоний/палитр — см. заметку про interpolationSpace и interpolation):

type ScaleInterpolation = 'rgb' | 'hsl' | 'oklab' | 'oklch'

CanvasGradientParams — дискриминированное объединение по type:

type CanvasGradientParams =
  | CanvasLinearGradientParams // { type: 'linear', stops, x0?, y0?, x1?, y1? }
  | CanvasRadialGradientParams // { type: 'radial', stops, x0?, y0?, r0?, x1?, y1?, r1? }
  | CanvasConicGradientParams // { type: 'conic', stops, startAngle?, x?, y? }

// Каждая точка: { color: string; offset: number } — отдельного экспортируемого имени для неё нет

Пример кастомного сериализатора / цветовой точки:

import type { ColorStop, GradientOptions } from 'css-magic-gradient'

const stops: ColorStop[] = [
  { color: '#ff6b6b', position: '0%' },
  { color: '#feca57', opacity: 0.8, position: '100%' },
]

const opts: GradientOptions = {
  direction: 'to right',
  interpolation: 'oklch',
}

Архитектура

css-magic-gradient
│
├── createLinearGradient      — linear-gradient / repeating-linear-gradient
│     Режим авто-яркости      — более светлая стартовая точка выводится из базового цвета
│     Режим ColorStop[]       — явный массив точек; непрозрачность точки → rgba()
│     CSS Color Level 4       — добавляет `in <space>` к CSS-объявлению градиента
│
├── createRadialGradient      — radial-gradient / repeating-radial-gradient
│     Режимы: авто / явный / слои / гармония
│     createRadialGradientLayers — генерирует массивы многокольцевых слоёв
│
├── createConicGradient       — conic-gradient / repeating-conic-gradient
│     createRainbowConicGradient — полный цикл тонов HSL
│
├── Генераторы цветовых гармоний
│     createComplementaryGradient / createTriadicGradient
│     createAnalogousGradient / createTetradicGradient
│     createSplitComplementaryGradient / createMonochromaticGradient
│     createHueWheelGradient
│     — все используют interpolateColors / createColorScale из color-value-tools
│
├── Генераторы палитр
│     createTintGradient / createShadeGradient / createToneGradient
│     — используют оттенки / тени / тона на основе Oklab из color-value-tools
│
├── Пресеты (src/presets.ts)
│     15 фиксированных строк градиентов
│
├── Доступность (src/accessibility.ts)
│     bestGradientTextColor    — выбирает #000 или #fff для лучшего контраста
│     gradientContrastRatio    — минимальный контраст по 11 выборочным точкам
│     gradientWcagLevel        — подробный GradientWcagReport
│     createAccessibleGradient — итеративно подстраивает, пока не достигнут целевой уровень
│     bestTextColor / wcagLevel / contrastRatio / isDark
│       — реэкспортированы напрямую из color-value-tools (одноцветные аналоги)
│
├── Утилиты CSS-переменных (src/css-variables.ts)
│     extractGradientVariables — парсит имена var() из строки градиента
│     resolveGradientVariables — подставляет значения переменных из карты
│
├── Экспорт в canvas (src/canvas-export.ts)
│     gradientToCanvasGradient — применяет точки к CanvasGradient
│     gradientToImageData      — рендерит в ImageData заданного размера
│     gradientToDataURL        — рендерит в data URL PNG
│
├── Интеграция с Vue 3 (src/vue-gradient-plugin.ts, только css-magic-gradient/vue)
│     VueGradientPlugin        — регистрирует $use* на инстансе Vue
│     useLinearGradient / useRadialGradient / useConicGradient
│     хуки use*Gradient        — ComputedRef<string>; SSR-безопасно; без доступа к DOM
│     Не реэкспортируется из корня пакета — это единственная точка входа,
│     которая реально импортирует `@vue/runtime-core`, так что ядро
│     остаётся загружаемым без установленного `vue` вообще
│
└── Интеграция с React (src/react-gradient-plugin.ts, только css-magic-gradient/react)
      useLinearGradient / useRadialGradient / useConicGradient
      хуки use*Gradient        — string через useMemo; SSR-безопасно; без зависимости от Vue

Совместимость с SSR

Ядро (все функции create*, пресеты, доступность, утилиты CSS-переменных) вообще не обращается к DOM — безопасно вызывать при SSR без каких-либо условий. Хуки Vue и React (css-magic-gradient/vue, css-magic-gradient/react) вычисляют строку градиента синхронно и тоже без доступа к browser API — так что они тоже SSR-безопасны из коробки, без <ClientOnly>/useEffect. Только функции экспорта в canvas обращаются к canvas API, и только при вызове — в окружении без document, OffscreenCanvas и серверной библиотеки canvas они выбрасывают понятную ошибку, а не падают тихо.

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

Точка входа	Peer-зависимости	Примечания
`css-magic-gradient`	нет	Основные функции, пресеты, доступность, утилиты CSS-переменных, экспорт в canvas — никогда не грузит `vue` или `react`, даже транзитивно
`css-magic-gradient/vue`	`vue ^3.0.0`	Плагин + хуки Vue — единственная точка входа, которой реально нужен `vue`
`css-magic-gradient/react`	`react ^17.0.0`	Только хуки React — без зависимости от Vue

Пакет поставляется как ESM + CommonJS (dist/*.js). Единственная runtime-зависимость основной точки входа — color-value-tools (математика цвета для генераторов гармоний, палитр и реэкспортированных одноцветных утилит WCAG).

// Ядро — vue и react не нужны
import {
  createLinearGradient,
  createTetradicGradient,
  sunsetGradient,
  createAccessibleGradient,
  extractGradientVariables,
  gradientToDataURL,
} from 'css-magic-gradient'

// Хуки Vue
import { useTetradicGradient } from 'css-magic-gradient/vue'

// Хуки React
import { useTintGradient } from 'css-magic-gradient/react'

Лицензия

MIT

Справочник ​

Типы TypeScript ​

Архитектура ​

Совместимость с SSR ​