Ключевое API

Core API - это небольшой набор функций, через который ты превращаешь строки градиентов в модели gradiente, валидируешь пользовательский ввод, нормализуешь output и отправляешь градиенты в рендереры.

Главная практическая идея: один раз распарсить градиент, а потом использовать одну и ту же модель везде.

Поток Core APIlinear-gradient(120deg, #ff74f6 0%, #405de6 55%, #12c2e9 100%)

Это превью отрисовано из parsed-модели gradiente через transformTo('css', gradient).

import { parse, transformTo } from 'gradiente'

const gradient = parse(
  'linear-gradient(120deg, #ff74f6 0%, #405de6 55%, #12c2e9 100%)'
)

const css = transformTo('css', gradient)

Строка остаётся удобным форматом для ввода и вывода. Parsed object становится стабильной моделью, которую можно читать, менять, сериализовать, сравнивать и трансформировать.

Карта API

parse()        string -> gradient object
isGradient()   unknown string -> boolean
format()       string | gradient object -> normalized string
transformTo()  string | gradient object -> renderer output
transformFrom() target output -> gradient object, если есть reverse transformer

В большинстве приложений работа начинается с parse(), пользовательский ввод проверяется через isGradient(), данные перед сохранением нормализуются через format(), а рендеринг делается через transformTo().

Парсинг В Модель

Используй parse(), когда нужно перестать работать с градиентом как с сырой строкой.

import { parse } from 'gradiente'

const gradient = parse('linear-gradient(to right, red 0%, blue 100%)')

gradient.type
gradient.getConfig()
gradient.toString()

Функция возвращает типизированный gradient instance. У градиентов со stop-точками можно дополнительно читать список stops.

import { parse } from 'gradiente'

const gradient = parse('linear-gradient(to right, red 0%, blue 100%)')

if ('getStops' in gradient) {
  const stops = gradient.getStops()
}

В этом главное отличие gradiente от string helper. Строка сначала превращается в переиспользуемую модель, и только потом отправляется в renderer.

Валидация Пользовательского Ввода

Используй isGradient(), когда ввод может быть невалидным и нужен безопасный boolean-check.

import { isGradient, parse } from 'gradiente'

const input = 'conic-gradient(from 74deg, #d53f96, #ef9439, #077fe9)'

if (isGradient(input)) {
  const gradient = parse(input)
}

Используй parse(), когда невалидный ввод должен выбросить ошибку с конкретной причиной. Используй isGradient(), когда проверка не должна ломать UI.

Нормализация Перед Сохранением

Используй format(), когда нужна каноническая строка после парсинга.

import { format } from 'gradiente'

const normalized = format('linear-gradient(to right, red, blue)')

format() принимает и строки, и уже созданные gradient objects.

import { format, parse } from 'gradiente'

const gradient = parse('linear-gradient(red, blue)')
const normalized = format(gradient)

Это удобно перед сохранением presets, хранением состояния редактора, синхронизацией данных или сравнением gradient definitions.

Рендеринг Через CSS

Используй target css, когда нужен CSS background value.

import { parse, transformTo } from 'gradiente'

const gradient = parse('linear-gradient(to right, #ff74f6, #405de6)')
const css = transformTo('css', gradient)

const preview = document.querySelector<HTMLElement>('.preview')

if (preview) {
  preview.style.backgroundImage = css
}

Визуальный результат:

HTML/CSS background, отрисованный через transformTo('css', gradient).

Для нативных CSS gradient kinds результатом будет CSS gradient string. Для gradiente-specific видов вроде diamond-gradient и mesh-gradient CSS transformer возвращает renderable adapter background.

import { transformTo } from 'gradiente'

const css = transformTo(
  'css',
  'diamond-gradient(at center, #5851db 0%, #fcb045 100%)'
)

Рендеринг Через Canvas 2D

Используй target canvas-2d, когда gradiente должен нарисовать градиент в CanvasRenderingContext2D.

import { transformTo } from 'gradiente'

const canvas = document.querySelector<HTMLCanvasElement>('canvas')
const paint = transformTo(
  'canvas-2d',
  'radial-gradient(circle at 30% 35%, #ffffff 0%, #ff74f6 35%, #405de6 100%)'
)

if (canvas) {
  const ctx = canvas.getContext('2d')

  if (ctx) {
    canvas.width = canvas.clientWidth
    canvas.height = canvas.clientHeight
    paint.draw(ctx, canvas.width, canvas.height)
  }
}

Визуальный результат:

Canvas 2D preview, отрисованный через transformTo('canvas-2d', gradient).

Возвращаемое значение зависит от renderer target. Для Canvas 2D это paint object с методом draw(ctx, width, height).

Рендеринг Через WebGL

Используй target canvas-webgl, когда градиент должен быть нарисован через WebGL.

import { transformTo } from 'gradiente'

const canvas = document.querySelector<HTMLCanvasElement>('canvas')
const paint = transformTo(
  'canvas-webgl',
  'conic-gradient(from 74deg at 50% 50%, #d53f96, #ef9439 63%, #077fe9)'
)

if (canvas) {
  canvas.width = canvas.clientWidth
  canvas.height = canvas.clientHeight
  paint.draw(canvas, canvas.width, canvas.height)
}

Визуальный результат:

Canvas WebGL preview, отрисованный через transformTo('canvas-webgl', gradient).

API остаётся тем же: приложение запрашивает target, а transformer возвращает output shape для этого target.

Рендеринг Через SVG

Используй target svg, когда нужен SVG paint server output.

import { transformTo } from 'gradiente'

const svg = document.querySelector<SVGSVGElement>('svg')
const rect = svg?.querySelector<SVGRectElement>('rect')
const paint = transformTo('svg', 'linear-gradient(to right, #ff74f6, #405de6)')

if (svg && rect) {
  svg.insertAdjacentHTML('afterbegin', paint.defs)
  rect.setAttribute('fill', paint.url)
}

SVG transformer возвращает описание с defs, url и serialized SVG data, которые нужны для применения градиента.

Импорт Из Других Targets

transformFrom() - обратная сторона transformer system.

import { transformFrom } from 'gradiente'

declare const token: unknown

const gradient = transformFrom(
  'design-token',
  'linear-gradient',
  token
)

Reverse transformation доступна тогда, когда зарегистрированный transformer module реализует from(). Так Core API остаётся симметричным, но не заставляет каждый renderer output быть обратимым.

Рабочая Модель

user input
  -> isGradient()
  -> parse()
  -> gradient object
  -> format()
  -> stored normalized string

gradient object
  -> transformTo('css')
  -> transformTo('canvas-2d')
  -> transformTo('canvas-webgl')
  -> transformTo('svg')
  -> transformTo('custom-target')

Дальше

• Трансформеры подробнее объясняют renderer targets.
• Собственные трансформеры объясняют, как добавлять свои targets.