Skip to content

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

33.9 KB
Raw Blame
/* eslint-disable max-lines -- scene node contracts are kept together as the public graph type surface */

import type { ExportFormatId } from './export-format'
import type { CanvasGuide } from './guides'
import type { InstanceOverrideState } from './instances/overrides'
import type { Color, Matrix, Rect, Vector } from './primitives'
import type { ShapeWithTextType } from './shape-with-text/kinds'

export interface SceneGraphEvents {
  'node:created': (node: SceneNode) => void
  'node:updated': (id: string, changes: Partial<SceneNode>) => void
  'node:previewUpdated': (id: string, changes: Partial<SceneNode>) => void
  'node:deleted': (id: string, parentId: string | null) => void
  'node:reparented': (nodeId: string, oldParentId: string | null, newParentId: string) => void
  'node:reordered': (
    nodeId: string,
    parentId: string,
    index: number,
    previousParentId: string | null
  ) => void
}

export type SceneGraphEventHandlers = Partial<{
  created: (node: SceneNode) => void
  updated: (id: string, changes: Partial<SceneNode>) => void
  previewUpdated: (id: string, changes: Partial<SceneNode>) => void
  deleted: (id: string, parentId: string | null) => void
  reparented: (nodeId: string, oldParentId: string | null, newParentId: string) => void
  reordered: (
    nodeId: string,
    parentId: string,
    index: number,
    previousParentId: string | null
  ) => void
}>

/** Hears about nodes as an edit adds and changes them, synchronously and before each change. */
export interface NodeChangeObserver {
  /** A node is about to change and is still as it was. */
  before: (node: SceneNode) => void
  /** A node was just added. */
  created: (node: SceneNode) => void
}

export type DocumentColorSpace = 'srgb' | 'display-p3'

/** What a document is for, as Figma keeps design files and FigJam boards apart. */
export type DocumentKind = 'design' | 'board'

export interface FigmaSourcePayload {
  rawSize: Vector | null
  rawTransform: Matrix | null
  rawNodeFields: Record<string, unknown>
  layout: FigmaLayoutMetadata | null
  symbolOverrides: unknown[]
  componentPropAssignments: unknown[]
  derivedSymbolData: unknown[]
  derivedSymbolDataLayoutVersion: number | null
  uniformScaleFactor: number | null
}

export interface SourceMetadata {
  format: 'fig' | null
  id: string | null
  orderKey: string | null
  editedFields: string[]
  fig: FigmaSourcePayload
}

export type HandleMirroring = 'NONE' | 'ANGLE' | 'ANGLE_AND_LENGTH'
export type WindingRule = 'NONZERO' | 'EVENODD'

export interface VectorVertex {
  x: number
  y: number
  strokeCap?: string
  strokeJoin?: string
  cornerRadius?: number
  handleMirroring?: HandleMirroring
}

export interface VectorSegment {
  start: number
  end: number
  tangentStart: Vector
  tangentEnd: Vector
}

export interface VectorRegion {
  windingRule: WindingRule
  loops: number[][]
  /** The region's own paints. Without them it draws the layer's fills, as in Figma. */
  fills?: Fill[]
  /** The shared fill style the region's paints come from. */
  fillStyleId?: string
}

export interface VectorNetwork {
  vertices: VectorVertex[]
  segments: VectorSegment[]
  regions: VectorRegion[]
}

export interface GeometryPath {
  windingRule: WindingRule
  commandsBlob: Uint8Array
}

export type NodeType =
  | 'CANVAS'
  | 'FRAME'
  | 'RECTANGLE'
  | 'ROUNDED_RECTANGLE'
  | 'ELLIPSE'
  | 'TEXT'
  | 'LINE'
  | 'STAR'
  | 'POLYGON'
  | 'VECTOR'
  | 'BOOLEAN_OPERATION'
  | 'GROUP'
  | 'SECTION'
  | 'COMPONENT'
  | 'COMPONENT_SET'
  | 'INSTANCE'
  | 'CONNECTOR'
  | 'SHAPE_WITH_TEXT'
  | 'STICKY'

export type FillType =
  | 'SOLID'
  | 'GRADIENT_LINEAR'
  | 'GRADIENT_RADIAL'
  | 'GRADIENT_ANGULAR'
  | 'GRADIENT_DIAMOND'
  | 'IMAGE'
  | 'VIDEO'
  | 'PATTERN'
  | 'NOISE'
  | 'CUSTOM'
export type BlendMode =
  | 'NORMAL'
  | 'DARKEN'
  | 'MULTIPLY'
  | 'LINEAR_BURN'
  | 'COLOR_BURN'
  | 'LIGHTEN'
  | 'SCREEN'
  | 'LINEAR_DODGE'
  | 'COLOR_DODGE'
  | 'OVERLAY'
  | 'SOFT_LIGHT'
  | 'HARD_LIGHT'
  | 'DIFFERENCE'
  | 'EXCLUSION'
  | 'HUE'
  | 'SATURATION'
  | 'COLOR'
  | 'LUMINOSITY'
  | 'PASS_THROUGH'
export type ImageScaleMode = 'FILL' | 'FIT' | 'CROP' | 'TILE'
export type NoiseType = 'MULTITONE' | 'MONOTONE' | 'DUOTONE'
export type PatternTileType = 'RECTANGULAR' | 'HORIZONTAL_HEXAGONAL' | 'VERTICAL_HEXAGONAL'
export type PatternAlignment = 'START' | 'CENTER' | 'END'

export interface GradientStop {
  color: Color
  position: number
}

export type GradientTransform = Matrix

export interface Fill {
  type: FillType
  color: Color
  opacity: number
  visible: boolean
  blendMode?: BlendMode
  gradientStops?: GradientStop[]
  gradientTransform?: GradientTransform
  imageHash?: string
  imageScaleMode?: ImageScaleMode
  /** A crop's image-space window; Fill, Fit and Tile ignore it. */
  imageTransform?: GradientTransform
  /** Clockwise turn of a Fill, Fit or Tile image, in multiples of 90°; a crop holds its own. */
  imageRotation?: number
  sourceNodeId?: string
  scale?: number
  spacing?: number
  patternSpacing?: Vector
  patternTileType?: PatternTileType
  verticalAlignment?: PatternAlignment
  horizontalAlignment?: PatternAlignment
  noiseType?: NoiseType
  density?: number
  noiseSize?: Vector
  customEffectId?: string
}

export type StrokeCap =
  | 'NONE'
  | 'ROUND'
  | 'SQUARE'
  | 'ARROW_LINES'
  | 'ARROW_EQUILATERAL'
  | 'TRIANGLE_FILLED'
  | 'DIAMOND_FILLED'
  | 'CIRCLE_FILLED'
export type StrokeJoin = 'MITER' | 'BEVEL' | 'ROUND'
export type SharedStyleType = 'FILL' | 'TEXT' | 'EFFECT' | 'GRID'
export type SharedStyleKind = 'fill' | 'stroke' | 'text' | 'effect' | 'grid'
export type MaskType = 'ALPHA' | 'VECTOR' | 'LUMINANCE'

export interface LayoutGrid {
  visible?: boolean
  color?: Color
  /** `STRIPES` is the archive's name for columns or rows, along `axis`. */
  pattern?: 'COLUMNS' | 'ROWS' | 'GRID' | 'STRIPES'
  axis?: 'X' | 'Y'
  type?: 'MIN' | 'CENTER' | 'MAX' | 'STRETCH'
  alignment?: 'MIN' | 'CENTER' | 'MAX' | 'STRETCH'
  numSections?: number
  /** Figma's plugin API reports an Auto count as `null` and accepts `Infinity` for it. */
  count?: number | null
  offset?: number
  sectionSize?: number
  gutterSize?: number
}

export interface SharedStyle {
  id: string
  nodeId: string
  name: string
  type: SharedStyleType
}

/** A stroke is a paint with the geometry that decides where it is drawn. */
export interface Stroke extends Fill {
  weight: number
  align: 'INSIDE' | 'CENTER' | 'OUTSIDE'
  cap?: StrokeCap
  join?: StrokeJoin
  dashPattern?: number[]
}

export interface Effect {
  type: 'DROP_SHADOW' | 'INNER_SHADOW' | 'LAYER_BLUR' | 'BACKGROUND_BLUR' | 'FOREGROUND_BLUR'
  color: Color
  offset: Vector
  radius: number
  spread: number
  visible: boolean
  blendMode?: BlendMode
  showShadowBehindNode?: boolean
}

export type ConstraintType = 'MIN' | 'CENTER' | 'MAX' | 'STRETCH' | 'SCALE'
export type TextAutoResize = 'NONE' | 'HEIGHT' | 'WIDTH_AND_HEIGHT' | 'TRUNCATE'

/** Where a connector end attaches to a layer: a side, the side Figma picks, or a fixed point. */
export type ConnectorMagnet =
  | 'NONE'
  | 'AUTO'
  | 'AUTO_HORIZONTAL'
  | 'TOP'
  | 'RIGHT'
  | 'BOTTOM'
  | 'LEFT'
  | 'CENTER'
  | 'EDGE'
  | 'ABSOLUTE'

/**
 * One end of a connector. Bound to a layer, it follows the layer by `magnet`, or by `position`
 * in the layer's own axes when the magnet is `NONE`. Free, `nodeId` is null and `position` is in
 * the connector's parent's axes.
 */
export interface ConnectorEndpoint {
  nodeId: string | null
  magnet: ConnectorMagnet
  position: Vector
}

export type ConnectorLineType = 'ELBOWED' | 'STRAIGHT' | 'CURVED'

/**
 * A segment of an elbow connector that was dragged into place: the line it runs along, through
 * `position`, in the connector's own axes. `position` lies midway along the segment as last drawn.
 */
export interface ConnectorControlPoint {
  position: Vector
  direction: 'HORIZONTAL' | 'VERTICAL'
}

/**
 * Where a connector's label was dragged along its line: `offset` of the way from the middle of
 * the line towards one end, by length, on the line or to one side of it. `ABOVE` is the side to
 * the left of the line's direction.
 */
export interface ConnectorLabelPosition {
  section: 'MIDDLE_TO_START' | 'MIDDLE_TO_END'
  offset: number
  offAxis: 'NONE' | 'ABOVE' | 'BELOW'
}
export type TextAlignVertical = 'TOP' | 'CENTER' | 'BOTTOM'
export type TextCase = 'ORIGINAL' | 'UPPER' | 'LOWER' | 'TITLE'
export type TextDecoration = 'NONE' | 'UNDERLINE' | 'STRIKETHROUGH'
export type TextDecorationStyle = 'SOLID' | 'DOTTED' | 'WAVY'
export type LeadingTrim = 'NONE' | 'CAP_HEIGHT'
export type TextDirection = 'AUTO' | 'LTR' | 'RTL'
export type LayoutDirection = 'AUTO' | 'LTR' | 'RTL'
/** Whether a paragraph is an item of a numbered list, a bulleted list, or no list. */
export type TextListType = 'NONE' | 'ORDERED' | 'UNORDERED'

/** How one paragraph of a text node (a line ending at a newline) sits in a list. */
/** Spacing a text sets for all its paragraphs and a paragraph can set for itself. */
export type TextParagraphSpacingField = 'listSpacing' | 'paragraphSpacing' | 'paragraphIndent'

export interface TextParagraphStyle {
  listType: TextListType
  /** Nesting level: 1–5 for list items; kept but not drawn for plain paragraphs. */
  indentation: number
  /** This paragraph's own spacing, in place of the text's; absent ones follow the text. */
  listSpacing?: number
  paragraphSpacing?: number
  paragraphIndent?: number
}

export interface FontVariation {
  axis: string
  value: number
}

export interface FontFeature {
  tag: string
  enabled: boolean
}

/** Where a stretch of text links to, as Figma's `HyperlinkTarget`: a URL, or a node by its ID. */
export interface HyperlinkTarget {
  type: 'URL' | 'NODE'
  value: string
}

/** The text fields a range of characters can bind to a variable, as Figma lists them. */
export const TEXT_BINDABLE_FIELDS = [
  'fontFamily',
  'fontSize',
  'fontStyle',
  'fontWeight',
  'letterSpacing',
  'lineHeight',
  'paragraphSpacing',
  'paragraphIndent'
] as const

export type TextBindableField = (typeof TEXT_BINDABLE_FIELDS)[number]

/** Variable IDs bound to text fields, by field. */
export type TextBoundVariables = Partial<Record<TextBindableField, string>>

/**
 * A line height or letter spacing as Figma keeps it: pixels, or a percent of the font size that
 * follows the size when it changes.
 */
export interface TextLength {
  value: number
  unit: 'PIXELS' | 'PERCENT'
}

export interface CharacterStyleOverride {
  fontWeight?: number
  italic?: boolean
  /** The characters' face by its font's own name for it; `null` is the face their weight picks. */
  fontStyle?: string | null
  textDecoration?: TextDecoration
  textDecorationStyle?: TextDecorationStyle
  textDecorationThickness?: number | null
  textDecorationFills?: Fill[]
  textDecorationSkipInk?: boolean
  textUnderlineOffset?: number | null
  fontSize?: number
  fontFamily?: string
  letterSpacing?: TextLength
  /** `null` is automatic, from the font. */
  lineHeight?: TextLength | null
  fills?: Fill[]
  fontVariations?: FontVariation[]
  /** Whether the characters' optical size follows their font size, in place of the text's own. */
  opticalSizeFromFontSize?: boolean
  fontFeatures?: FontFeature[]
  textLanguage?: string | null
  textCase?: TextCase
  /** A link over the characters; `null`, like leaving it out, links nowhere. */
  hyperlink?: HyperlinkTarget | null
  /** The text style the characters use in place of the text's own; `null` uses none. */
  textStyleId?: string | null
  /** The fill style the characters use in place of the text's own; `null` uses none. */
  fillStyleId?: string | null
  /** The characters' text field bindings, in place of the text's own. */
  boundVariables?: TextBoundVariables
}

export interface StyleRun {
  start: number
  length: number
  style: CharacterStyleOverride
}

export interface ArcData {
  startingAngle: number
  endingAngle: number
  innerRadius: number
}

export type LayoutMode = 'NONE' | 'HORIZONTAL' | 'VERTICAL' | 'GRID'
/** A node's sizing along one axis; fill is stored on the child, see `layoutSizing`. */
export type LayoutSizing = 'FIXED' | 'HUG' | 'FILL'
/** Whether an auto-layout frame keeps its size or hugs its children along one of its axes. */
export type AxisSizingMode = 'FIXED' | 'HUG'

export type GridTrackSizing = 'FIXED' | 'FR' | 'AUTO'

export interface GridTrack {
  sizing: GridTrackSizing
  value: number
}

export interface GridPosition {
  column: number
  row: number
  columnSpan: number
  rowSpan: number
}
export type LayoutAlign = 'MIN' | 'CENTER' | 'MAX' | 'SPACE_BETWEEN'
export type LayoutCounterAlign = 'MIN' | 'CENTER' | 'MAX' | 'STRETCH' | 'BASELINE'
export type LayoutAlignSelf = 'AUTO' | 'MIN' | 'CENTER' | 'MAX' | 'STRETCH' | 'BASELINE'
export type LayoutWrap = 'NO_WRAP' | 'WRAP'

export interface PluginDataEntry {
  pluginId: string
  key: string
  value: string
}

/** A fixed width or height in pixels an export is scaled to, instead of a multiplier. */
export interface ExportSize {
  type: 'WIDTH' | 'HEIGHT'
  value: number
}

/** The colour profile an export is written in; the document's own unless set. */
export type ExportColorProfile = 'DOCUMENT' | 'SRGB' | 'DISPLAY_P3_V4'

/**
 * One export a layer keeps. The options past `scale` and `format` are Figma's and read as Figma's
 * defaults when left out.
 */
export interface ExportSetting {
  scale: number
  format: ExportFormatId
  /** Appended to the file name. */
  suffix?: string
  /** A size that replaces `scale`. */
  size?: ExportSize
  /** Only the layer, without what overlaps it (default true). */
  contentsOnly?: boolean
  /** The layer's box rather than everything it draws, for text (default false). */
  useAbsoluteBounds?: boolean
  colorProfile?: ExportColorProfile
  /** SVG: text as outlines rather than `<text>` (default true). */
  svgOutlineText?: boolean
  /** SVG: every layer's name as its element's `id` (default false). */
  svgIdAttribute?: boolean
  /** SVG: strokes as strokes where possible rather than masked outlines (default true). */
  svgSimplifyStroke?: boolean
}

export interface PluginRelaunchDataEntry {
  pluginId: string
  command: string
  message: string
  isDeleted: boolean
}

/**
 * One derived glyph outline for display (path text / missing-font fidelity).
 * Figma import is one producer; OpenPencil editing and reflow can regenerate it.
 * commandsBlob is in font units; paint multiplies by fontSize (and scaleX/Y).
 */
export interface TextPathData {
  network: VectorNetwork
  normalizedSize: Vector
  /** Where on the start segment the text starts, from 0 at its start to 1 at its end. */
  tValue: number
  forward: boolean
  /** The segment the text starts on, which Figma marks in the network blob; 0 when unmarked. */
  startSegment?: number
}

export interface DerivedTextGlyph {
  /** UTF-16 source-text cluster start, when supplied by the shaping source. */
  firstCharacter?: number
  commandsBlob: Uint8Array
  x: number
  y: number
  fontSize: number
  /** Figma Glyph.rotation — radians, not degrees. Zero for axis-aligned text. */
  rotation?: number
  /**
   * Horizontal advance in pixels at `fontSize`, before `scaleX`, when the shaping source gave
   * one; where the glyph ends, so decorations stop at the text rather than the layer's edge.
   */
  advance?: number
  /**
   * Accumulated non-uniform resize scale (default 1). Paint order is
   * translate → scale(scaleX,Y) → rotate → scale(fontSize,-fontSize) so
   * anisotropic stretch matches scaleGeometryPaths(strokeGeometry).
   * Do not fold this into fontSize or rotated letters desync from outlines.
   */
  scaleX?: number
  scaleY?: number
  /**
   * The code points of the emoji this glyph stands for, sequence and all. Its outline is only a
   * placeholder square a 1 em wide; the emoji's image is drawn there instead, as Figma does.
   */
  emojiCodePoints?: number[]
  /** The image set Figma draws the emoji from, when the file names one other than Apple's. */
  emojiImageSet?: 'NOTO'
}

export interface SymbolLink {
  uri: string
  displayName?: string
  displayText?: string
}

export interface VariantPropSpec {
  propDefId: string
  value: string
}

export type FigmaLayoutMetadata = Partial<
  Record<
    | 'stackMode'
    | 'stackCounterAlign'
    | 'stackJustify'
    | 'stackCounterAlignItems'
    | 'stackPrimaryAlignItems'
    | 'stackPrimarySizing'
    | 'stackCounterSizing'
    | 'stackWrap'
    | 'stackPositioning'
    | 'stackChildAlignSelf',
    string
  > &
    Record<
      | 'stackSpacing'
      | 'stackPadding'
      | 'stackPaddingRight'
      | 'stackPaddingBottom'
      | 'stackVerticalPadding'
      | 'stackHorizontalPadding'
      | 'stackChildPrimaryGrow'
      | 'stackCounterSpacing',
      number
    > &
    Record<'bordersTakeSpace' | 'stackReverseZIndex', boolean>
>

export interface LibraryAssetIdentity {
  libraryId: string
  assetKey: string
  revisionId: string
}

export interface LibraryAssetSource {
  identity: LibraryAssetIdentity
  sourceNodeId: string | null
  readOnly: boolean
}

export interface EnabledLibraryBinding {
  libraryId: string
  revisionId: string
  enabled: boolean
}

/** The library a document publishes as. */
export interface SourceLibraryPublication {
  libraryId: string
  revisionId: string
  name: string
  catalogSource?: string
}

/** A reply in a canvas comment thread. */
export interface CommentReply {
  id: string
  author: string
  /** The author's collaboration color when they wrote it, for their avatar. */
  authorColor?: Color
  /** Markdown: bold, italic, strikethrough, links and lists. */
  text: string
  createdAt: string
  deleted?: boolean
}

/** A canvas comment thread, kept in the document's root plugin data. */
export interface CommentThread {
  id: string
  pageId: string
  /** Page name when the pin was placed, for readers of the raw data. */
  pageName?: string
  /** Top-level layer under the pin; the pin follows it when it moves. */
  nodeId?: string | null
  nodeName?: string | null
  /** Offset from the layer's top-left corner, in canvas units. */
  offsetX?: number
  offsetY?: number
  /** Canvas position when the pin was last saved; used when the layer is gone. */
  x: number
  y: number
  author: string
  /** The author's collaboration color when they wrote it, for their avatar. */
  authorColor?: Color
  /** Markdown: bold, italic, strikethrough, links and lists. */
  text: string
  createdAt: string
  /** Bumped on every change. */
  updatedAt: string
  resolved: boolean
  resolvedAt?: string | null
  /** Deleted threads stay as tombstones so a stale copy cannot bring them back. */
  deleted?: boolean
  replies: CommentReply[]
}

export interface SceneNode {
  id: string
  type: NodeType
  name: string
  parentId: string | null
  childIds: string[]

  x: number
  y: number
  width: number
  height: number
  rotation: number
  source: SourceMetadata
  /** Materialized layout hint imported or generated outside the live Yoga layout pass. */
  derivedLayout: Partial<Rect> | null

  fills: Fill[]
  strokes: Stroke[]
  effects: Effect[]
  layoutGrids: LayoutGrid[]
  guides: CanvasGuide[]
  fillStyleId: string | null
  strokeStyleId: string | null
  textStyleId: string | null
  effectStyleId: string | null
  gridStyleId: string | null
  sharedStyleType: SharedStyleType | null
  opacity: number

  cornerRadius: number
  topLeftRadius: number
  topRightRadius: number
  bottomRightRadius: number
  bottomLeftRadius: number
  independentCorners: boolean
  cornerSmoothing: number

  visible: boolean
  locked: boolean
  clipsContent: boolean

  blendMode: BlendMode

  text: string
  fontSize: number
  fontFamily: string
  fontWeight: number
  italic: boolean
  /**
   * The face by the name its font gives it ("Semi Bold", "Book", "Condensed Bold"), which Figma
   * finds a font's face by; `null` is the face the weight and slant pick in the family.
   */
  fontStyle: string | null
  textAlignHorizontal: 'LEFT' | 'CENTER' | 'RIGHT' | 'JUSTIFIED'
  textDirection: TextDirection
  textLanguage: string | null
  textAlignVertical: TextAlignVertical
  textAutoResize: TextAutoResize
  textCase: TextCase
  textDecoration: TextDecoration
  textDecorationStyle: TextDecorationStyle
  textDecorationThickness: number | null
  textDecorationFills: Fill[]
  textDecorationSkipInk: boolean
  textUnderlineOffset: number | null
  leadingTrim: LeadingTrim
  /** `null` is automatic, from the font. */
  lineHeight: TextLength | null
  letterSpacing: TextLength
  maxLines: number | null
  /**
   * One entry per paragraph of `text`, in order. Missing entries are plain paragraphs, so text
   * without lists keeps this empty.
   */
  textParagraphs: TextParagraphStyle[]
  /** Space after a list item followed by another; a paragraph's own value comes first. */
  listSpacing: number
  /** Space after a paragraph other than between two list items. */
  paragraphSpacing: number
  /** Indent of the first line of each plain paragraph. */
  paragraphIndent: number
  /** Whether list markers hang outside the text box instead of indenting the items. */
  hangingList: boolean

  styleRuns: StyleRun[]
  fontVariations: FontVariation[]
  /**
   * Whether a variable font's optical size follows the font size, as Figma's "Set optical size
   * automatically" does by default; when it does not, the `opsz` in `fontVariations` applies.
   */
  opticalSizeFromFontSize: boolean
  fontFeatures: FontFeature[]

  horizontalConstraint: ConstraintType
  verticalConstraint: ConstraintType

  layoutMode: LayoutMode
  layoutDirection: LayoutDirection
  layoutWrap: LayoutWrap
  primaryAxisAlign: LayoutAlign
  counterAxisAlign: LayoutCounterAlign
  primaryAxisSizing: AxisSizingMode
  counterAxisSizing: AxisSizingMode
  itemSpacing: number
  counterAxisSpacing: number
  paddingTop: number
  paddingRight: number
  paddingBottom: number
  paddingLeft: number

  layoutPositioning: 'AUTO' | 'ABSOLUTE'
  layoutGrow: number
  layoutAlignSelf: LayoutAlignSelf

  vectorNetwork: VectorNetwork | null
  handleMirroring: HandleMirroring
  booleanOperation: 'UNION' | 'SUBTRACT' | 'INTERSECT' | 'EXCLUDE' | undefined
  fillGeometry: GeometryPath[]
  strokeGeometry: GeometryPath[]

  arcData: ArcData | null

  strokeCap: StrokeCap
  strokeJoin: StrokeJoin
  dashPattern: number[]

  borderTopWeight: number
  borderRightWeight: number
  borderBottomWeight: number
  borderLeftWeight: number
  independentStrokeWeights: boolean

  /**
   * The weight and alignment a node keeps for its strokes, as Figma keeps them on the node: they
   * last while it has no strokes, and a stroke added to it takes them. Each stroke still carries
   * its own `weight` and `align`, which win while the node has strokes.
   */
  strokeWeight: number
  strokeAlign: Stroke['align']

  strokeMiterLimit: number

  minWidth: number | null
  maxWidth: number | null
  minHeight: number | null
  maxHeight: number | null
  /**
   * The size whose proportions the layer keeps, as Figma stores it: the width and height it had
   * when the ratio was locked, not a reduced ratio. Null leaves the proportions free.
   */
  targetAspectRatio: Vector | null

  /** A connector's ends and the line between them; null on other layers. */
  connectorStart: ConnectorEndpoint | null
  connectorEnd: ConnectorEndpoint | null
  connectorLineType: ConnectorLineType
  connectorStartCap: StrokeCap
  connectorEndCap: StrokeCap
  /**
   * An elbow connector's segments between its first and last, in order, once one was dragged;
   * empty while it routes itself. Kept, unused, while the line is straight or curved.
   */
  connectorControlPoints: ConnectorControlPoint[]
  /**
   * A curved connector's two cubic control points, in the connector's own axes, once its curve
   * was dragged; null while it curves by itself. Kept, unused, while the line is not curved.
   */
  connectorCurveHandles: [Vector, Vector] | null
  /** Where a connector's label was dragged to; null while it sits midway along the line. */
  connectorLabelPosition: ConnectorLabelPosition | null

  isMask: boolean
  maskType: MaskType
  maskIsOutline: boolean

  gridTemplateColumns: GridTrack[]
  gridTemplateRows: GridTrack[]
  gridColumnGap: number
  gridRowGap: number
  gridPosition: GridPosition | null

  counterAxisAlignContent: 'AUTO' | 'SPACE_BETWEEN'
  itemReverseZIndex: boolean
  strokesIncludedInLayout: boolean

  expanded: boolean
  textTruncation: 'DISABLED' | 'ENDING'
  autoRename: boolean

  pointCount: number
  starInnerRadius: number
  /** The FigJam kind a SHAPE_WITH_TEXT draws; its label is the node's own text. */
  shapeWithTextType: ShapeWithTextType
  /** The height a shape with text was given; it grows past it to fit its label. 0 is unset. */
  shapeUserHeight: number
  /**
   * Whether a shape with text keeps its height and cuts its label off with "…" instead of growing,
   * as FigJam does once the shape's height was set.
   */
  shapeTruncates: boolean

  componentId: string | null
  instanceOverrides: InstanceOverrideState
  componentPropertyDefinitions: ComponentPropertyDefinition[]
  componentPropertyReferences: ComponentPropertyReference[]
  componentPropertyAssignments: Record<string, string>
  componentPropertyValues: Record<string, string>
  componentKey: string | null
  sourceLibraryKey: string | null
  publishId: string | null
  overrideKey: string | null
  sharedSymbolVersion: string | null
  publishedVersion: string | null
  librarySource: LibraryAssetSource | null
  isPublishable: boolean
  isSymbolPublishable: boolean
  /**
   * On an instance inside a component: its properties show on instances of that component,
   * as Figma's `isExposedInstance`.
   */
  isExposedInstance: boolean
  symbolDescription: string
  symbolLinks: SymbolLink[]
  variantPropSpecs: VariantPropSpec[]

  boundVariables: Record<string, string>
  /** Multipliers from bound numeric values to this occurrence's scene units. */
  variableBindingScales: Partial<Record<string, number>>
  /** Numeric units for new declarations owned by this node's occurrence scope. */
  variableAssignmentScales: Partial<Record<string, number>>
  /** Explicit coordinate scale relative to the containing component definition. */
  componentScale: number
  variableModes: VariableModeMap
  exportSettings: ExportSetting[]
  /**
   * The id of the status a team gave the layer, a state of the document's workflow such as Ready
   * for dev. It stays while the layer sits where it cannot show one; `effectiveStatus` tells
   * whether it shows.
   */
  status: string | null

  pluginData: PluginDataEntry[]
  pluginRelaunchData: PluginRelaunchDataEntry[]

  internalOnly: boolean

  flipX: boolean
  flipY: boolean

  textPicture: Uint8Array | null
  derivedTextGlyphs: DerivedTextGlyph[] | null
  /**
   * How far a text's lines reach down from its top: measured at its width when its text or width
   * changes, or read from the lines a file saved, and never saved itself. A fixed-size box does not
   * clip them, as in Figma, so its visual bounds reach this far. Null when not known.
   */
  derivedTextHeight: number | null
  /** Format-neutral layout path for text-on-path nodes. */
  textPathData: TextPathData | null
  /** Node-local box that maps textPathData into the node coordinate space. */
  textPathBox: Rect | null
}

export type ComponentPropertyType = 'VARIANT' | 'TEXT' | 'BOOLEAN' | 'INSTANCE_SWAP' | 'SLOT'

/** `SLOT_CONTENT` marks a frame whose children are the slot's content. */
export type ComponentPropertyReferenceField = 'VISIBLE' | 'TEXT' | 'INSTANCE_SWAP' | 'SLOT_CONTENT'

export interface ComponentPropertyReference {
  propertyId: string
  field: ComponentPropertyReferenceField
}

/** Guidance for a slot property; Figma reports a breach but still accepts the content. */
export interface SlotSettings {
  minChildren?: number
  maxChildren?: number
  allowPreferredValuesOnly: boolean
  displayEmptyByDefault: boolean
  /** Content added to the slot fills its counter axis. */
  stretchChildOnInsert: boolean
}

/**
 * For a `SLOT` property, an instance assignment (whatever its value) means the instance owns
 * that slot's content: the slot frame's children in the instance, which component sync keeps.
 */
export interface ComponentPropertyDefinition {
  id: string
  name: string
  type: ComponentPropertyType
  defaultValue: string
  variantOptions?: string[]
  preferredValues?: string[]
  description?: string
  slotSettings?: SlotSettings
}

export type VariableType = 'COLOR' | 'FLOAT' | 'STRING' | 'BOOLEAN'
export interface VariableAlias {
  aliasId: string
}

/** Figma's two-argument color expression; opacity is a percentage, not an alpha multiplier. */
export interface VariableColorExpression {
  expression: 'COMPOSE_COLOR'
  color: Color | VariableAlias
  opacity: number | VariableAlias
}

export type VariableLiteral = Color | number | string | boolean
/** The arithmetic, comparison, logic and conversions a formula combines values with. */
export const VARIABLE_FORMULA_OPERATORS = [
  'add',
  'subtract',
  'multiply',
  'divide',
  'negate',
  'equal',
  'notEqual',
  'less',
  'lessOrEqual',
  'greater',
  'greaterOrEqual',
  'and',
  'or',
  'not',
  'text',
  'truthy',
  'if'
] as const
export type VariableFormulaOperator = (typeof VARIABLE_FORMULA_OPERATORS)[number]
export interface VariableFormulaOperation {
  operator: VariableFormulaOperator
  operands: VariableFormulaNode[]
}
export type VariableFormulaNode = VariableLiteral | VariableAlias | VariableFormulaOperation
export interface VariableFormula {
  expression: 'FORMULA'
  type: VariableType
  value: VariableFormulaNode
}
/**
 * An imported expression OpenPencil cannot evaluate, kept as the file wrote it so saving writes it
 * back. `references` holds one entry per alias in `value`, in the order the format walks them, and
 * `null` where the alias names a variable this document does not have. `modes` holds the mode id of
 * each mode key in `value`, in the same walk order.
 */
export interface VariableUnsupportedExpression {
  expression: 'UNSUPPORTED'
  /** The function name the file gives, such as `VAR_MODE_LOOKUP`. */
  function: string
  value: Record<string, unknown>
  references: (string | null)[]
  modes: string[]
}
export type VariableValue =
  | VariableLiteral
  | VariableAlias
  | VariableColorExpression
  | VariableFormula
  | VariableUnsupportedExpression
export type VariableModeMap = Record<string, string>

/** Property pickers a variable is offered in, as Figma names them. */
export const VARIABLE_SCOPES = [
  'ALL_SCOPES',
  'TEXT_CONTENT',
  'CORNER_RADIUS',
  'WIDTH_HEIGHT',
  'GAP',
  'ALL_FILLS',
  'FRAME_FILL',
  'SHAPE_FILL',
  'TEXT_FILL',
  'STROKE',
  'STROKE_FLOAT',
  'EFFECT_FLOAT',
  'EFFECT_COLOR',
  'OPACITY',
  'FONT_STYLE',
  'FONT_FAMILY',
  'FONT_SIZE',
  'LINE_HEIGHT',
  'LETTER_SPACING',
  'PARAGRAPH_SPACING',
  'PARAGRAPH_INDENT',
  'FONT_VARIATIONS',
  'TRANSFORM'
] as const
export type VariableScope = (typeof VARIABLE_SCOPES)[number]

export const CODE_SYNTAX_PLATFORMS = ['WEB', 'ANDROID', 'iOS'] as const
export type CodeSyntaxPlatform = (typeof CODE_SYNTAX_PLATFORMS)[number]

/**
 * The CSS unit a numeric token is written in. Lengths (`px`, `rem`) stay in canvas pixels in
 * the document and convert only when written as CSS; the other units store the number as written.
 */
export const TOKEN_UNITS = ['none', 'px', 'rem', '%', 'ms', 's', 'deg'] as const
export type TokenUnit = (typeof TOKEN_UNITS)[number]

/**
 * CSS written in place of a number mode's value, such as `clamp(1rem, 4vw, 1.5rem)`. While the
 * mode holds a plain number, `resolved` records it, so a number later edited elsewhere, Figma
 * included, shows the CSS no longer describes it.
 */
export interface TokenExpression {
  css: string
  resolved?: number
}

export interface Variable {
  id: string
  name: string
  type: VariableType
  collectionId: string
  valuesByMode: Record<string, VariableValue>
  description: string
  hiddenFromPublishing: boolean
  /** Absent means every scope. */
  scopes?: VariableScope[]
  /**
   * Per-platform code snippets, as Figma's Dev Mode shows them. A `WEB` snippet of `--x` or
   * `var(--x)` names the token's CSS custom property; otherwise the name is derived.
   */
  codeSyntax?: Partial<Record<CodeSyntaxPlatform, string>>
  /** FLOAT only. Absent means inferred when written as CSS. */
  unit?: TokenUnit
  /** Raw CSS by mode id, for values a number cannot express (`clamp()`, `calc()`). */
  expressions?: Record<string, TokenExpression>
  pluginData?: PluginDataEntry[]
  /** Published library key (from NodeChange.key). Used for assetRef resolution in colorVar. */
  key?: string
  /** Published library version (from NodeChange.version). Used for assetRef resolution in colorVar. */
  version?: string
}

/** Scalar numeric node fields accepted by numeric property controls. */
export type NumericNodeProperty = {
  [K in keyof SceneNode]-?: SceneNode[K] extends number ? K : never
}[keyof SceneNode]

export interface VariableCollectionMode {
  modeId: string
  name: string
  /**
   * Where the mode applies in CSS: a selector (`[data-theme="dark"]`, `.compact`) or an
   * at-rule prelude (`@media (max-width: 640px)`). Absent means the default for its axis.
   */
  condition?: string
  /** Where Figma lists the mode, as the file saved it; Figma orders a collection's modes by it. */
  sortPosition?: string
}

export interface VariableCollection {
  id: string
  name: string
  /** The default mode comes first, as in Figma. */
  modes: VariableCollectionMode[]
  defaultModeId: string
  variableIds: string[]
  /**
   * The attribute that switches a mode with no condition of its own, `data-theme` for
   * `[data-theme="dark"]`. Absent means one named after the collection.
   */
  modeAttribute?: string
  pluginData?: PluginDataEntry[]
  /**
   * Published library key, for a collection the file copies from a library. Such a collection
   * belongs to the library: Figma lists it with the library's, not the file's own.
   */
  key?: string
  /** Published library version, which references by key carry with it. */
  version?: string
}

/** Whether a collection is a library's copy, which takes no variables or modes of the file's. */
export function isLibraryCollection(collection: Pick<VariableCollection, 'key'>): boolean {
  return !!collection.key
}

/** An HTML attribute name a stylesheet can select on unescaped: `data-theme`, `theme`. */
export const MODE_ATTRIBUTE_PATTERN = /^[A-Za-z_][\w-]*$/

export function isModeAttributeName(name: string): boolean {
  return name.length <= 100 && MODE_ATTRIBUTE_PATTERN.test(name)
}