Skip to content

AI-native design editor. Open-source Figma alternative.

8.7 KB
Raw Blame
import type {
  BlurEffectNormal,
  DropShadowEffect,
  Effect as PluginEffect,
  InnerShadowEffect
} from '@figma/plugin-typings/plugin-api-standalone'
import * as v from 'valibot'

import type { BlendMode, Effect } from '@open-pencil/scene-graph'
import type { EffectBindingProperty } from '@open-pencil/scene-graph/variables'

import { TRANSPARENT } from '#core/constants'
import { invalid, parseFigma } from '#core/figma-api/validation'
import type { FigmaVariableAlias } from '#core/figma-api/variables/values'

/** Blend modes in the order Figma lists them in its messages. */
const BLEND_MODE_KEYS = {
  PASS_THROUGH: true,
  NORMAL: true,
  DARKEN: true,
  MULTIPLY: true,
  LINEAR_BURN: true,
  COLOR_BURN: true,
  LIGHTEN: true,
  SCREEN: true,
  LINEAR_DODGE: true,
  COLOR_DODGE: true,
  OVERLAY: true,
  SOFT_LIGHT: true,
  HARD_LIGHT: true,
  DIFFERENCE: true,
  EXCLUSION: true,
  HUE: true,
  SATURATION: true,
  COLOR: true,
  LUMINOSITY: true
} satisfies Record<BlendMode, true>

export const BLEND_MODES = Object.keys(BLEND_MODE_KEYS) as BlendMode[]

/** Effect kinds Figma's plugin API accepts that OpenPencil does not model yet. */
const UNSUPPORTED_EFFECT_TYPES = new Set(['NOISE', 'TEXTURE', 'GLASS', 'SHADER'])

// Figma rejects Infinity as well as NaN ("Number must be finite").
const finiteSchema = v.pipe(v.number(), v.finite())
const unitSchema = v.pipe(finiteSchema, v.minValue(0), v.maxValue(1))
const nonNegativeSchema = v.pipe(finiteSchema, v.minValue(0))

const colorSchema = v.strictObject({ r: unitSchema, g: unitSchema, b: unitSchema, a: unitSchema })
const vectorSchema = v.strictObject({ x: finiteSchema, y: finiteSchema })
const aliasSchema = v.strictObject({ type: v.literal('VARIABLE_ALIAS'), id: v.string() })
const shadowBindingsSchema = v.optional(
  v.strictObject({
    color: v.optional(aliasSchema),
    radius: v.optional(aliasSchema),
    spread: v.optional(aliasSchema),
    offsetX: v.optional(aliasSchema),
    offsetY: v.optional(aliasSchema)
  })
)
const blurBindingsSchema = v.optional(v.strictObject({ radius: v.optional(aliasSchema) }))

const shadowEntries = {
  color: colorSchema,
  offset: vectorSchema,
  radius: nonNegativeSchema,
  spread: v.optional(finiteSchema),
  visible: v.boolean(),
  blendMode: v.picklist(BLEND_MODES),
  boundVariables: shadowBindingsSchema
}

const effectSchema = v.variant('type', [
  v.strictObject({
    type: v.literal('DROP_SHADOW'),
    ...shadowEntries,
    showShadowBehindNode: v.optional(v.boolean())
  }),
  v.strictObject({ type: v.literal('INNER_SHADOW'), ...shadowEntries }),
  v.strictObject({
    type: v.picklist(['LAYER_BLUR', 'BACKGROUND_BLUR']),
    radius: nonNegativeSchema,
    visible: v.boolean(),
    blurType: v.optional(v.literal('NORMAL'), 'NORMAL'),
    boundVariables: blurBindingsSchema
  })
])

const effectsSchema = v.array(effectSchema)

/** An effect as Figma's plugin API reads and writes it (`Effect` in `@figma/plugin-typings`). */
export type FigmaEffect = v.InferOutput<typeof effectSchema>

/** Why OpenPencil cannot keep `effect`, and the field that says so, or null when it can. */
function unsupportedEffectReason(effect: unknown): { message: string; field: string } | null {
  const type: unknown = v.is(v.object({ type: v.unknown() }), effect) ? effect.type : undefined
  if (typeof type === 'string' && UNSUPPORTED_EFFECT_TYPES.has(type)) {
    return { message: `${type} effects are not supported`, field: 'type' }
  }
  if (v.is(v.object({ blurType: v.literal('PROGRESSIVE') }), effect)) {
    return { message: 'Progressive blur is not supported', field: 'blurType' }
  }
  return null
}

function unsupportedEffect(value: unknown): string | null {
  if (!Array.isArray(value)) return null
  for (const [index, effect] of value.entries()) {
    const reason = unsupportedEffectReason(effect)
    if (reason) return `${reason.message} at [${index}].${reason.field}`
  }
  return null
}

/** The shadows and plain blurs OpenPencil models, in the shapes Figma's plugin typings give them. */
type ModelledPluginEffect = DropShadowEffect | InnerShadowEffect | BlurEffectNormal

function isPluginShadow(
  effect: ModelledPluginEffect
): effect is DropShadowEffect | InnerShadowEffect {
  return effect.type === 'DROP_SHADOW' || effect.type === 'INNER_SHADOW'
}

function modelledPluginEffect(method: string, effect: PluginEffect): ModelledPluginEffect {
  if (effect.type === 'DROP_SHADOW' || effect.type === 'INNER_SHADOW') return effect
  if (effect.type === 'LAYER_BLUR' || effect.type === 'BACKGROUND_BLUR') {
    if (effect.blurType !== 'PROGRESSIVE') return effect
  }
  const reason = unsupportedEffectReason(effect)
  throw new Error(`in ${method}: ${reason?.message ?? `${effect.type} effects are not supported`}`)
}

/**
 * `effect` with `bindings` as `setBoundVariableForEffect` returns it: fields in Figma's order, a
 * shadow's spread at 0. Effects OpenPencil does not model are refused, as `effects` refuses them.
 */
export function boundEffectCopy(
  method: string,
  effect: PluginEffect,
  bindings: (effect: ModelledPluginEffect) => FigmaEffectBindings
): FigmaEffect {
  const modelled = modelledPluginEffect(method, effect)
  // The copy owns its aliases, so changing them leaves the effect it was made from alone.
  const boundVariables = structuredClone(bindings(modelled))
  const { visible, radius } = modelled
  if (!isPluginShadow(modelled)) {
    return { type: modelled.type, visible, radius, boundVariables, blurType: 'NORMAL' }
  }
  const shadow = {
    visible,
    radius,
    boundVariables,
    color: { ...modelled.color },
    offset: { ...modelled.offset },
    spread: 0,
    blendMode: modelled.blendMode
  }
  if (modelled.type === 'INNER_SHADOW') return { type: modelled.type, ...shadow }
  return modelled.showShadowBehindNode === undefined
    ? { type: modelled.type, ...shadow }
    : { type: modelled.type, ...shadow, showShadowBehindNode: modelled.showShadowBehindNode }
}

/** Check `value` against Figma's effect shapes and convert it to scene effects. */
export function parseFigmaEffects(value: unknown): Effect[] {
  const method = 'set_effects'
  const unsupported = unsupportedEffect(value)
  if (unsupported) throw invalid(method, unsupported, 'effects')
  return parseFigma(effectsSchema, value, method, 'effects').map(toSceneEffect)
}

/** `value` as scene effects when it holds valid Figma effects, or null. */
export function tryParseFigmaEffects(value: unknown): Effect[] | null {
  if (unsupportedEffect(value)) return null
  const result = v.safeParse(effectsSchema, value)
  return result.success ? result.output.map(toSceneEffect) : null
}

function toSceneEffect(effect: FigmaEffect): Effect {
  if (effect.type === 'DROP_SHADOW' || effect.type === 'INNER_SHADOW') {
    return {
      type: effect.type,
      color: { ...effect.color },
      offset: { ...effect.offset },
      radius: effect.radius,
      spread: effect.spread ?? 0,
      visible: effect.visible,
      // Figma accepts PASS_THROUGH on shadows but stores NORMAL; it is a layer blend mode.
      blendMode: effect.blendMode === 'PASS_THROUGH' ? 'NORMAL' : effect.blendMode,
      ...(effect.type === 'DROP_SHADOW' && effect.showShadowBehindNode !== undefined
        ? { showShadowBehindNode: effect.showShadowBehindNode }
        : {})
    }
  }
  return {
    type: effect.type,
    color: { ...TRANSPARENT },
    offset: { x: 0, y: 0 },
    radius: effect.radius,
    spread: 0,
    visible: effect.visible
  }
}

/** The variables an effect's properties are bound to, as its `boundVariables` names them. */
export type FigmaEffectBindings = Partial<Record<EffectBindingProperty, FigmaVariableAlias>>

/**
 * A scene effect in the shape Figma's `effects` getter returns, with the variables its properties
 * are bound to.
 */
export function toFigmaEffect(effect: Effect, bindings: FigmaEffectBindings = {}): FigmaEffect {
  if (
    effect.type === 'LAYER_BLUR' ||
    effect.type === 'FOREGROUND_BLUR' ||
    effect.type === 'BACKGROUND_BLUR'
  ) {
    return {
      // `.fig` files call a layer blur FOREGROUND_BLUR; the plugin API calls it LAYER_BLUR.
      type: effect.type === 'BACKGROUND_BLUR' ? 'BACKGROUND_BLUR' : 'LAYER_BLUR',
      visible: effect.visible,
      radius: effect.radius,
      boundVariables: bindings.radius ? { radius: bindings.radius } : {},
      blurType: 'NORMAL'
    }
  }
  const shadow = {
    visible: effect.visible,
    radius: effect.radius,
    boundVariables: bindings,
    color: { ...effect.color },
    offset: { ...effect.offset },
    spread: effect.spread,
    blendMode: effect.blendMode ?? 'NORMAL'
  }
  return effect.type === 'DROP_SHADOW'
    ? {
        type: 'DROP_SHADOW',
        ...shadow,
        // The renderer draws the shadow behind the node unless this is `false`.
        showShadowBehindNode: effect.showShadowBehindNode ?? true
      }
    : { type: 'INNER_SHADOW', ...shadow }
}