AI-native design editor. Open-source Figma alternative.
import * as v from 'valibot'
import type { BlendMode, Fill, GradientTransform, ImageScaleMode } from '@open-pencil/scene-graph'
import { BLACK } from '@open-pencil/scene-graph/constants'
import {
gradientTransformRows,
IDENTITY_GRADIENT_TRANSFORM
} from '@open-pencil/scene-graph/gradient'
import type { Color, Vector } from '@open-pencil/scene-graph/primitives'
import { invalid, parseFigma } from '#core/figma-api/validation'
import { BLEND_MODES } from './effects'
import type { FigmaTransform } from './types'
import { variableAlias, type FigmaVariableAlias } from './variables/values'
/** The paint types Figma's `fills` and `strokes` take, in the order its message lists them. */
const PAINT_TYPES = [
'SOLID',
'SHADER',
'GRADIENT_LINEAR',
'GRADIENT_RADIAL',
'GRADIENT_ANGULAR',
'GRADIENT_DIAMOND',
'IMAGE',
'VIDEO'
] as const
/** Paint types Figma's plugin API takes that OpenPencil does not model yet. */
const UNSUPPORTED_PAINT_TYPES = new Set(['SHADER'])
const GRADIENT_TYPES = [
'GRADIENT_LINEAR',
'GRADIENT_RADIAL',
'GRADIENT_ANGULAR',
'GRADIENT_DIAMOND'
] as const
const SCALE_MODES = ['FILL', 'FIT', 'CROP', 'TILE'] as const satisfies readonly ImageScaleMode[]
type ImageFilters = Record<
'exposure' | 'contrast' | 'saturation' | 'temperature' | 'tint' | 'highlights' | 'shadows',
number
>
/** OpenPencil keeps no image filters; Figma reads every slider at 0 until one moves. */
const NO_FILTERS: ImageFilters = {
exposure: 0,
contrast: 0,
saturation: 0,
temperature: 0,
tint: 0,
highlights: 0,
shadows: 0
}
/** Figma's videos are named by the SHA-1 of their bytes. */
const SHA1_HASH = /^[0-9a-f]{40}$/i
/** Figma's message for a value that is none of `options`. */
const unitSchema = v.pipe(v.number(), v.minValue(0), v.maxValue(1))
const aliasSchema = v.object({ type: v.literal('VARIABLE_ALIAS'), id: v.string() })
const colorBindingSchema = v.optional(v.strictObject({ color: v.optional(aliasSchema) }))
const paintEntries = {
visible: v.optional(v.boolean()),
opacity: v.optional(unitSchema),
blendMode: v.optional(v.picklist(BLEND_MODES))
}
// Figma checks a transform's rows itself, after the paint's other fields.
const transformSchema = v.optional(v.unknown())
// Image filter sliders run from -1 to 1.
const filterSchema = v.optional(v.pipe(v.number(), v.minValue(-1), v.maxValue(1)))
const mediaEntries = {
scaleMode: v.picklist(SCALE_MODES),
scalingFactor: v.optional(v.number()),
rotation: v.optional(v.number()),
filters: v.optional(
v.strictObject({
exposure: filterSchema,
contrast: filterSchema,
saturation: filterSchema,
temperature: filterSchema,
tint: filterSchema,
highlights: filterSchema,
shadows: filterSchema
})
),
...paintEntries
}
const paintSchema = v.variant('type', [
v.strictObject({
type: v.literal('SOLID'),
// A solid colour is RGB; Figma takes an alpha as the paint's opacity.
color: v.strictObject({
r: unitSchema,
g: unitSchema,
b: unitSchema,
a: v.optional(unitSchema)
}),
...paintEntries,
boundVariables: colorBindingSchema
}),
v.strictObject({
type: v.picklist(GRADIENT_TYPES),
gradientTransform: transformSchema,
gradientStops: v.array(
v.strictObject({
position: unitSchema,
color: v.strictObject({ r: unitSchema, g: unitSchema, b: unitSchema, a: unitSchema }),
boundVariables: colorBindingSchema
})
),
...paintEntries
}),
v.strictObject({
type: v.literal('IMAGE'),
imageHash: v.nullable(v.string()),
imageTransform: transformSchema,
...mediaEntries
}),
v.strictObject({
type: v.literal('VIDEO'),
videoHash: v.nullable(v.string()),
videoTransform: transformSchema,
...mediaEntries
})
])
type ParsedPaint = v.InferOutput<typeof paintSchema>
type PaintBase = {
readonly visible?: boolean
readonly opacity?: number
readonly blendMode?: BlendMode
}
type ColorBinding = { readonly boundVariables?: { readonly color?: FigmaVariableAlias } }
type MediaFields = PaintBase & {
readonly scaleMode: ImageScaleMode
readonly scalingFactor?: number
readonly rotation?: number
readonly filters?: Partial<ImageFilters>
}
/** A paint OpenPencil models that Figma's plugin API has no type for, read as the model holds it. */
export type OpenPencilPaint = Omit<Fill, 'type' | 'gradientTransform' | 'imageTransform'> & {
readonly type: 'NOISE' | 'CUSTOM'
readonly gradientTransform?: FigmaTransform
readonly imageTransform?: FigmaTransform
}
/**
* A paint as Figma's plugin API gives and takes it (`Paint` in `@figma/plugin-typings`): a solid
* colour is RGB with its alpha in the opacity, transforms are two rows of three, and an image or
* video names its scale mode, rotation, and tile scaling as Figma does. Like Figma, the setters
* refuse a pattern; OpenPencil's own paints read as {@link OpenPencilPaint}.
*/
export type FigmaPaint =
| (PaintBase &
ColorBinding & {
readonly type: 'SOLID'
readonly color: Omit<Color, 'a'>
})
| (PaintBase & {
readonly type: (typeof GRADIENT_TYPES)[number]
readonly gradientTransform: FigmaTransform
readonly gradientStops: ReadonlyArray<
ColorBinding & { readonly position: number; readonly color: Color }
>
})
| (MediaFields & {
readonly type: 'IMAGE'
readonly imageHash: string | null
readonly imageTransform?: FigmaTransform
})
| (MediaFields & {
readonly type: 'VIDEO'
readonly videoHash: string | null
readonly videoTransform?: FigmaTransform
})
| (PaintBase & {
readonly type: 'PATTERN'
readonly sourceNodeId: string
readonly tileType: NonNullable<Fill['patternTileType']>
readonly scalingFactor: number
readonly spacing: Vector
readonly horizontalAlignment: NonNullable<Fill['horizontalAlignment']>
})
| OpenPencilPaint
type ReadBase = Required<PaintBase>
/** Figma's complaint about a paint type it does not take, or OpenPencil does not model. */
function typeProblem(value: readonly unknown[]): string | null {
for (const [index, paint] of value.entries()) {
// A paint without a type is refused as one of an unknown type, as in Figma.
if (!paint || typeof paint !== 'object') continue
const { type } = paint as { type?: unknown }
if (typeof type === 'string' && UNSUPPORTED_PAINT_TYPES.has(type)) {
return `${type} paints are not supported at [${index}].type`
}
if (!(PAINT_TYPES as readonly unknown[]).includes(type)) {
return `Expected [${index}].type to be one of the following: ${PAINT_TYPES.join(', ')}`
}
}
return null
}
type TransformField = 'gradientTransform' | 'imageTransform' | 'videoTransform'
function isRow(value: unknown): value is [number, number, number] {
return (
Array.isArray(value) &&
value.length === 3 &&
value.every((item) => typeof item === 'number' && Number.isFinite(item))
)
}
/** Figma's complaint about `value` as a transform, or null when it is two rows of three numbers. */
function transformProblem(value: unknown): string | null {
if (value === undefined) return 'Required value missing'
if (!Array.isArray(value))
return `Expected array, received ${value === null ? 'null' : typeof value}`
if (value.length < 2) return 'Too small: expected array to have exactly 2 items'
if (value.length > 2) return 'Too big: expected array to have exactly 2 items'
return value.every(isRow) ? null : 'Expected array of 3 numbers'
}
/** Where a paint at `index` in the list a script passes to `method` sets `property`. */
type PaintSite = { index: number; method: string; property: string }
/**
* The scene transform `value` a paint holds in `field`, which Figma requires of a gradient. Figma
* takes only two rows of three numbers and throws the way its `fills` and `strokes` setters do.
*/
function sceneTransform(
value: unknown,
field: TransformField,
site: PaintSite
): GradientTransform | undefined {
if (value === undefined && field !== 'gradientTransform') return undefined
const problem = transformProblem(value)
if (problem) {
const at = `[${site.index}].${field}`
throw invalid(
site.method,
`Expected ${at} to be one of the following, but none matched:\n ${problem} at ${at}`,
site.property
)
}
const [[m00, m01, m02], [m10, m11, m12]] = value as FigmaTransform
return { m00, m01, m02, m10, m11, m12 }
}
function sceneFill(paint: ParsedPaint, site: PaintSite): Fill {
const base = {
visible: paint.visible ?? true,
opacity: paint.opacity ?? 1,
...(paint.blendMode && { blendMode: paint.blendMode })
}
if (paint.type === 'SOLID') {
const { r, g, b, a } = paint.color
// Figma keeps a solid paint's alpha in its opacity, so a colour's alpha stands in for an
// opacity left out, as `figma.util.solidPaint` gives it.
return { type: 'SOLID', ...base, color: { r, g, b, a: 1 }, opacity: paint.opacity ?? a ?? 1 }
}
if (paint.type === 'IMAGE' || paint.type === 'VIDEO') {
const [hash, imageTransform] =
paint.type === 'IMAGE'
? [paint.imageHash, sceneTransform(paint.imageTransform, 'imageTransform', site)]
: [paint.videoHash, sceneTransform(paint.videoTransform, 'videoTransform', site)]
return {
type: paint.type,
...base,
color: { ...BLACK },
imageScaleMode: paint.scaleMode,
...(hash !== null && { imageHash: hash }),
...(imageTransform && { imageTransform }),
...(paint.rotation !== undefined && { imageRotation: paint.rotation }),
...(paint.scalingFactor !== undefined && { scale: paint.scalingFactor })
}
}
return {
type: paint.type,
...base,
color: { ...BLACK },
gradientStops: paint.gradientStops.map(({ position, color }) => ({
position,
color: { ...color }
})),
gradientTransform: sceneTransform(paint.gradientTransform, 'gradientTransform', site)
}
}
/**
* Check `value` against Figma's paint shapes and convert it to scene paints. Throws Figma's
* message for `method` setting `property`, listing every problem on its own line.
*/
export function parseFigmaPaints(value: unknown, method = 'set_fills', property = 'fills'): Fill[] {
const unsupported = Array.isArray(value) ? typeProblem(value) : null
if (unsupported) throw invalid(method, unsupported, property)
const paints = parseFigma(v.array(paintSchema), value, method, property)
for (const paint of paints) {
if (paint.type === 'VIDEO' && paint.videoHash !== null && !SHA1_HASH.test(paint.videoHash)) {
throw new Error(`in ${method}: Invalid SHA1 hash`)
}
}
return paints.map((paint, index) => sceneFill(paint, { index, method, property }))
}
function rows(transform: GradientTransform | undefined): FigmaTransform {
return gradientTransformRows(transform ?? IDENTITY_GRADIENT_TRANSFORM)
}
/**
* An image or video paint as Figma reads it. Outside crop mode it reads the identity transform, a
* scaling factor of 1 unless tiled, and its rotation; a crop holds its own rotation, so it reads
* none.
*/
function figmaMediaPaint(paint: Fill, type: 'IMAGE' | 'VIDEO', base: ReadBase): FigmaPaint {
const scaleMode = paint.imageScaleMode ?? 'FILL'
const crop = scaleMode === 'CROP'
const media = {
...base,
scaleMode,
scalingFactor: scaleMode === 'TILE' ? (paint.scale ?? 1) : 1,
...(!crop && { rotation: paint.imageRotation ?? 0 }),
filters: { ...NO_FILTERS }
}
const transform = rows(crop ? paint.imageTransform : undefined)
const hash = paint.imageHash ?? null
return type === 'IMAGE'
? { type, ...media, imageTransform: transform, imageHash: hash }
: { type, ...media, videoTransform: transform, videoHash: hash }
}
function figmaPatternPaint(paint: Fill, base: ReadBase): FigmaPaint {
return {
type: 'PATTERN',
...base,
sourceNodeId: paint.sourceNodeId ?? '',
tileType: paint.patternTileType ?? 'RECTANGULAR',
scalingFactor: paint.scale ?? 1,
spacing: { ...(paint.patternSpacing ?? { x: 0, y: 0 }) },
horizontalAlignment: paint.horizontalAlignment ?? 'START'
}
}
function openPencilPaint(paint: Fill, type: OpenPencilPaint['type']): OpenPencilPaint {
const { gradientTransform, imageTransform, ...rest } = paint
return {
...structuredClone(rest),
type,
...(gradientTransform && { gradientTransform: rows(gradientTransform) }),
...(imageTransform && { imageTransform: rows(imageTransform) })
}
}
/** `paint` as Figma's plugin API reads it, its colour bound to `variableId` when given. */
export function toFigmaPaint(paint: Fill, variableId?: string): FigmaPaint {
const base: ReadBase = {
visible: paint.visible,
opacity: paint.opacity,
blendMode: paint.blendMode ?? 'NORMAL'
}
const { type } = paint
if (type === 'SOLID') {
const { r, g, b } = paint.color
return {
type,
...base,
color: { r, g, b },
boundVariables: variableId ? { color: variableAlias(variableId) } : {}
}
}
if (type === 'IMAGE' || type === 'VIDEO') return figmaMediaPaint(paint, type, base)
if (type === 'PATTERN') return figmaPatternPaint(paint, base)
if (type === 'NOISE' || type === 'CUSTOM') return openPencilPaint(paint, type)
return {
type,
...base,
gradientStops: (paint.gradientStops ?? []).map(({ position, color }) => ({
position,
color: { ...color }
})),
gradientTransform: rows(paint.gradientTransform)
}
}