@seed-design/figma 0.0.0-alpha-20260324091316

package/src/normalizer/types.ts

@@ -0,0 +1,208 @@
+import type * as FigmaRestSpec from "@figma/rest-api-spec";
+
+export type NormalizedIsLayerTrait = Pick<FigmaRestSpec.IsLayerTrait, "type" | "id" | "name"> & {
+  boundVariables?: Pick<
+    NonNullable<FigmaRestSpec.IsLayerTrait["boundVariables"]>,
+    | "fills"
+    | "strokes"
+    | "itemSpacing"
+    | "counterAxisSpacing"
+    | "bottomLeftRadius"
+    | "bottomRightRadius"
+    | "topLeftRadius"
+    | "topRightRadius"
+    | "paddingBottom"
+    | "paddingLeft"
+    | "paddingRight"
+    | "paddingTop"
+    | "maxHeight"
+    | "minHeight"
+    | "maxWidth"
+    | "minWidth"
+    | "fontSize"
+    | "fontWeight"
+    | "lineHeight"
+    | "size"
+  >;
+};
+
+export type NormalizedCornerTrait = Pick<
+  FigmaRestSpec.CornerTrait,
+  "cornerRadius" | "rectangleCornerRadii"
+>;
+
+export type NormalizedHasChildrenTrait = {
+  children: NormalizedSceneNode[];
+};
+
+export type NormalizedHasLayoutTrait = Pick<
+  FigmaRestSpec.HasLayoutTrait,
+  | "layoutAlign"
+  | "layoutGrow"
+  | "absoluteBoundingBox"
+  | "relativeTransform"
+  | "layoutPositioning"
+  | "layoutSizingHorizontal"
+  | "layoutSizingVertical"
+  | "minHeight"
+  | "minWidth"
+  | "maxHeight"
+  | "maxWidth"
+>;
+
+export type NormalizedSolidPaint = FigmaRestSpec.SolidPaint;
+
+export type NormalizedPaint =
+  | NormalizedSolidPaint
+  | FigmaRestSpec.GradientPaint
+  | FigmaRestSpec.ImagePaint;
+
+export type NormalizedHasGeometryTrait = Omit<
+  Pick<FigmaRestSpec.HasGeometryTrait, "fills" | "strokes" | "strokeWeight">,
+  "fills" | "strokes"
+> & {
+  fills: NormalizedPaint[];
+  strokes: NormalizedPaint[];
+  fillStyleKey?: string;
+};
+
+export type NormalizedShadow =
+  | (Pick<
+      FigmaRestSpec.DropShadowEffect,
+      "color" | "offset" | "radius" | "spread" | "boundVariables"
+    > &
+      Required<Pick<FigmaRestSpec.DropShadowEffect, "type">>)
+  | (Pick<
+      FigmaRestSpec.InnerShadowEffect,
+      "color" | "offset" | "radius" | "spread" | "boundVariables"
+    > &
+      Required<Pick<FigmaRestSpec.InnerShadowEffect, "type">>);
+
+export type NormalizedHasEffectsTrait = Omit<FigmaRestSpec.HasEffectsTrait, "effects"> & {
+  effects: NormalizedShadow[];
+  effectStyleKey?: string;
+};
+
+export type NormalizedHasFramePropertiesTrait = Pick<
+  FigmaRestSpec.HasFramePropertiesTrait,
+  | "layoutMode"
+  | "layoutWrap"
+  | "paddingLeft"
+  | "paddingRight"
+  | "paddingTop"
+  | "paddingBottom"
+  | "primaryAxisAlignItems"
+  | "primaryAxisSizingMode"
+  | "counterAxisAlignItems"
+  | "counterAxisSizingMode"
+  | "itemSpacing"
+  | "counterAxisSpacing"
+>;
+
+export interface NormalizedTextSegment {
+  characters: string;
+  start: number;
+  end: number;
+  style: {
+    fontFamily?: string;
+    fontWeight?: number;
+    fontSize?: number;
+    italic?: boolean;
+    textDecoration?: string;
+    letterSpacing?: number;
+    /**
+     * in pixels
+     */
+    lineHeight?: number;
+  };
+}
+
+export type NormalizedTypePropertiesTrait = Pick<
+  FigmaRestSpec.TypePropertiesTrait,
+  "style" | "characters"
+> & {
+  segments: NormalizedTextSegment[];
+
+  textStyleKey?: string;
+};
+
+export type NormalizedDefaultShapeTrait = NormalizedIsLayerTrait &
+  NormalizedHasLayoutTrait &
+  NormalizedHasGeometryTrait &
+  NormalizedHasEffectsTrait;
+
+export type NormalizedFrameTrait = NormalizedIsLayerTrait &
+  NormalizedHasLayoutTrait &
+  NormalizedHasGeometryTrait &
+  NormalizedHasEffectsTrait &
+  NormalizedHasChildrenTrait &
+  NormalizedCornerTrait &
+  NormalizedHasFramePropertiesTrait;
+
+export interface NormalizedFrameNode extends NormalizedFrameTrait {
+  type: FigmaRestSpec.FrameNode["type"];
+}
+
+export interface NormalizedRectangleNode
+  extends NormalizedDefaultShapeTrait,
+    NormalizedCornerTrait {
+  type: FigmaRestSpec.RectangleNode["type"];
+}
+
+export interface NormalizedTextNode
+  extends NormalizedDefaultShapeTrait,
+    NormalizedTypePropertiesTrait {
+  type: FigmaRestSpec.TextNode["type"];
+}
+
+export interface NormalizedComponentNode extends NormalizedFrameTrait {
+  type: FigmaRestSpec.ComponentNode["type"];
+}
+
+export interface NormalizedInstanceNode extends NormalizedFrameTrait {
+  type: FigmaRestSpec.InstanceNode["type"];
+
+  componentProperties: {
+    [key: string]: FigmaRestSpec.ComponentProperty & {
+      componentKey?: string;
+      componentSetKey?: string;
+    };
+  };
+
+  componentKey: string;
+
+  componentSetKey?: string;
+
+  overrides?: FigmaRestSpec.InstanceNode["overrides"];
+
+  children: NormalizedSceneNode[];
+}
+
+export interface NormalizedVectorNode extends NormalizedDefaultShapeTrait, NormalizedCornerTrait {
+  type: FigmaRestSpec.VectorNode["type"];
+}
+
+export interface NormalizedBooleanOperationNode
+  extends NormalizedIsLayerTrait,
+    NormalizedHasChildrenTrait,
+    NormalizedHasLayoutTrait,
+    NormalizedHasGeometryTrait,
+    NormalizedHasEffectsTrait {
+  type: FigmaRestSpec.BooleanOperationNode["type"];
+}
+
+export interface NormalizedUnhandledNode {
+  type: "UNHANDLED";
+  id: string;
+  original: FigmaRestSpec.Node | SceneNode;
+}
+
+export type NormalizedSceneNode =
+  | NormalizedFrameNode
+  | NormalizedRectangleNode
+  | NormalizedTextNode
+  | NormalizedComponentNode
+  | NormalizedInstanceNode
+  | NormalizedVectorNode
+  | NormalizedBooleanOperationNode
+  | NormalizedUnhandledNode;

package/src/utils/common.ts

@@ -0,0 +1,38 @@
+import { camelCase } from "change-case";
+
+export function ensureArray<T>(maybeArray: T | T[]): T[] {
+  if (Array.isArray(maybeArray)) {
+    return maybeArray;
+  }
+
+  return [maybeArray];
+}
+
+export function exists<T>(value: T | null | undefined): value is T {
+  return value != null;
+}
+
+export function compactObject<T extends Record<string, unknown>>(obj: T): T {
+  return Object.fromEntries(Object.entries(obj).filter(([, value]) => value != null)) as T;
+}
+
+export function objectEntries<T extends Record<string, unknown>>(obj: T) {
+  return Object.entries(obj) as [keyof T, T[keyof T]][];
+}
+
+export function identity<T>(value: T) {
+  return value;
+}
+
+/**
+ * camelCase but preserve underscore between numbers.
+ * temporary workaround to avoid x1_5 -> x15
+ * @example "color-1_5" -> "color1_5"
+ */
+export function camelCasePreserveUnderscoreBetweenNumbers(input: string) {
+  return camelCase(input, {
+    mergeAmbiguousCharacters: false,
+  })
+    .replaceAll(/(\D)_(\d)/g, "$1$2")
+    .replaceAll(/(\d)_(\D)/g, "$1$2");
+}

package/src/utils/css.ts

@@ -0,0 +1,19 @@
+import type { RGBA } from "@figma/rest-api-spec";
+
+export function toCssPixel(value: number): `${number}px` {
+  return `${value}px`;
+}
+
+export function toCssRem(value: number): `${number}rem` {
+  return `${value / 16}rem`;
+}
+
+export function toCssRgba(
+  color: RGBA,
+): `rgba(${number}, ${number}, ${number}, ${number})` | `rgb(${number}, ${number}, ${number})` {
+  if (color.a === 1) {
+    return `rgb(${Math.round(color.r * 255)}, ${Math.round(color.g * 255)}, ${Math.round(color.b * 255)})`;
+  }
+
+  return `rgba(${Math.round(color.r * 255)}, ${Math.round(color.g * 255)}, ${Math.round(color.b * 255)}, ${color.a})`;
+}

package/src/utils/figma-gradient.ts

@@ -0,0 +1,72 @@
+/**
+ * @see https://gist.github.com/yagudaev/0c2b89674c6aee8b38cd379752ef58d0
+ */
+
+const identityMatrixHandlePositions = [
+  [0, 1, 0],
+  [0.5, 0.5, 1],
+  [1, 1, 1],
+];
+
+/**
+ * Inverts a 2x3 affine transformation matrix
+ * For a 2x3 matrix [[a, b, c], [d, e, f]], we treat it as a 3x3 matrix with [0, 0, 1] as the third row
+ */
+function inv(matrix: number[][]): number[][] {
+  const [[a, b, c], [d, e, f]] = matrix;
+
+  // Calculate determinant of the 2x2 linear part
+  const det = a * e - b * d;
+
+  if (Math.abs(det) < 1e-10) {
+    throw new Error("Matrix is not invertible");
+  }
+
+  // Invert the 2x2 linear part
+  const invDet = 1 / det;
+  const a_inv = e * invDet;
+  const b_inv = -b * invDet;
+  const d_inv = -d * invDet;
+  const e_inv = a * invDet;
+
+  // Calculate the inverted translation
+  const c_inv = -(a_inv * c + b_inv * f);
+  const f_inv = -(d_inv * c + e_inv * f);
+
+  return [
+    [a_inv, b_inv, c_inv],
+    [d_inv, e_inv, f_inv],
+  ];
+}
+
+/**
+ * Multiplies a 2x3 matrix with a 3x3 matrix
+ * Result is a 2x3 matrix
+ */
+function multiply(matrix1: number[][], matrix2: number[][]): number[][] {
+  const [[a, b, c], [d, e, f]] = matrix1;
+  const result: number[][] = [[], []];
+
+  // For each column in matrix2
+  for (let col = 0; col < matrix2[0].length; col++) {
+    // First row of result
+    result[0][col] = a * matrix2[0][col] + b * matrix2[1][col] + c * matrix2[2][col];
+    // Second row of result
+    result[1][col] = d * matrix2[0][col] + e * matrix2[1][col] + f * matrix2[2][col];
+  }
+
+  return result;
+}
+
+export function convertTransformToGradientHandles(transform: number[][]) {
+  const inverseTransform = inv(transform);
+
+  // point matrix
+  const mp = multiply(inverseTransform, identityMatrixHandlePositions);
+
+  return [
+    { x: mp[0][0], y: mp[1][0] },
+    { x: mp[0][1], y: mp[1][1] },
+    { x: mp[0][2], y: mp[1][2] },
+  ];
+}

package/src/utils/figma-node.ts

@@ -0,0 +1,95 @@
+import type {
+  NormalizedHasGeometryTrait,
+  NormalizedInstanceNode,
+  NormalizedSceneNode,
+  NormalizedSolidPaint,
+} from "../normalizer";
+
+export function traverseNode(
+  node: NormalizedSceneNode,
+  callback: (node: NormalizedSceneNode) => void,
+) {
+  callback(node);
+
+  if (!("children" in node)) return;
+
+  for (const child of node.children) {
+    traverseNode(child, callback);
+  }
+}
+
+export function findOne(
+  node: NormalizedSceneNode,
+  callback: (node: NormalizedSceneNode) => boolean,
+) {
+  let result: NormalizedSceneNode | undefined;
+
+  traverseNode(node, (n) => {
+    if (callback(n)) {
+      result = n;
+    }
+  });
+
+  return result;
+}
+
+export function findAll(
+  node: NormalizedSceneNode,
+  callback: (node: NormalizedSceneNode) => boolean,
+) {
+  const result: NormalizedSceneNode[] = [];
+
+  traverseNode(node, (n) => {
+    if (callback(n)) {
+      result.push(n);
+    }
+  });
+
+  return result;
+}
+
+export function findAllInstances<T>({ node, key }: { node: NormalizedSceneNode; key: string }) {
+  return findAll(
+    node,
+    (n) => n.type === "INSTANCE" && (n.componentKey === key || n.componentSetKey === key),
+  ) as (Omit<NormalizedInstanceNode, "componentProperties"> & { componentProperties: T })[];
+}
+
+export function getFirstSolidFill(node: NormalizedHasGeometryTrait) {
+  const fills = node.fills.filter(
+    (fill): fill is NormalizedSolidPaint =>
+      fill.type === "SOLID" && (!("visible" in fill) || fill.visible === true),
+  );
+
+  if (fills.length === 0) {
+    return undefined;
+  }
+
+  return fills[0];
+}
+
+export function getFirstFillVariable(node: NormalizedHasGeometryTrait) {
+  const fill = getFirstSolidFill(node);
+
+  return fill?.boundVariables?.color;
+}
+
+export function getFirstStroke(node: NormalizedHasGeometryTrait) {
+  const strokes =
+    node.strokes?.filter(
+      (stroke): stroke is NormalizedSolidPaint =>
+        stroke.type === "SOLID" && (!("visible" in stroke) || stroke.visible === true),
+    ) ?? [];
+
+  if (strokes.length === 0) {
+    return undefined;
+  }
+
+  return strokes[0];
+}
+
+export function getFirstStrokeVariable(node: NormalizedHasGeometryTrait) {
+  const stroke = getFirstStroke(node);
+
+  return stroke?.boundVariables?.color;
+}

package/src/utils/figma-variable.ts

@@ -0,0 +1,49 @@
+import type { VariableScope } from "@figma/rest-api-spec";
+
+// boundVariable.id is formatted as "VariableID:{key}/{localId}", we have to extract the key
+export function sanitizeVariableId(id: string) {
+  return id.replace("VariableID:", "").split("/")[0]!;
+}
+
+export function isVariableAlias(value: unknown): value is VariableAlias {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "type" in value &&
+    value.type === "VARIABLE_ALIAS"
+  );
+}
+
+export function isIdenticalVariableValue(
+  value1: string | number | boolean | RGBA,
+  value2: string | number | boolean | RGBA,
+) {
+  if (typeof value1 !== typeof value2) {
+    return false;
+  }
+
+  if (typeof value1 === "string" || typeof value1 === "number" || typeof value1 === "boolean") {
+    return value1 === value2;
+  }
+
+  return (
+    value1.r === (value2 as RGBA).r &&
+    value1.g === (value2 as RGBA).g &&
+    value1.b === (value2 as RGBA).b &&
+    value1.a === (value2 as RGBA).a
+  );
+}
+
+export function isInsideScope(variable: { scopes: VariableScope[] }, scope: VariableScope) {
+  if (variable.scopes.includes("ALL_SCOPES")) {
+    return true;
+  }
+
+  if (variable.scopes.includes("ALL_FILLS")) {
+    if (scope === "FRAME_FILL" || scope === "SHAPE_FILL" || scope === "TEXT_FILL") {
+      return true;
+    }
+  }
+
+  return variable.scopes.includes(scope);
+}