@seed-design/figma 0.0.2 → 0.0.5

package/src/normalizer/from-plugin.ts

@@ -7,9 +7,14 @@ import type {
   NormalizedComponentNode,
   NormalizedInstanceNode,
   NormalizedVectorNode,
+  NormalizedBooleanOperationNode,
 } from "./types";
 
 export function createPluginNormalizer() {
+  async function normalizeNodes(nodes: readonly SceneNode[]): Promise<NormalizedSceneNode[]> {
+    return Promise.all(nodes.filter((node) => node.visible).map(normalizeNode));
+  }
+
   async function normalizeNode(node: SceneNode): Promise<NormalizedSceneNode> {
     if (node.type === "FRAME") {
       return normalizeFrameNode(node);
@@ -23,6 +28,9 @@ export function createPluginNormalizer() {
     if (node.type === "VECTOR") {
       return normalizeVectorNode(node);
     }
+    if (node.type === "BOOLEAN_OPERATION") {
+      return normalizeBooleanOperationNode(node);
+    }
     if (node.type === "TEXT") {
       return normalizeTextNode(node);
     }
@@ -33,7 +41,11 @@ export function createPluginNormalizer() {
       return normalizeInstanceNode(node);
     }
 
-    throw new Error(`Unimplemented node type: ${node.type}`);
+    return {
+      type: "UNHANDLED",
+      id: node.id,
+      original: node,
+    };
   }
 
   async function normalizeFrameNode(node: FrameNode): Promise<NormalizedFrameNode> {
@@ -44,7 +56,7 @@ export function createPluginNormalizer() {
       boundVariables: await normalizeBoundVariables(node),
       ...normalizeRadiusProps(node),
       ...normalizeAutolayoutProps(node),
-      children: await Promise.all(node.children.map(normalizeNode)),
+      children: await normalizeNodes(node.children),
     };
   }
 
@@ -75,7 +87,7 @@ export function createPluginNormalizer() {
       counterAxisSpacing: node.inferredAutoLayout?.counterAxisSpacing ?? undefined,
       fills: [],
       strokes: [],
-      children: await Promise.all(node.children.map(normalizeNode)),
+      children: await normalizeNodes(node.children),
     };
   }
 
@@ -100,6 +112,18 @@ export function createPluginNormalizer() {
     };
   }
 
+  async function normalizeBooleanOperationNode(
+    node: BooleanOperationNode,
+  ): Promise<NormalizedBooleanOperationNode> {
+    return {
+      type: node.type,
+      id: node.id,
+      name: node.name,
+      boundVariables: await normalizeBoundVariables(node),
+      children: await normalizeNodes(node.children),
+      ...normalizeShapeProps(node),
+    };
+  }
   async function normalizeTextNode(node: TextNode): Promise<NormalizedTextNode> {
     const segments = node.getStyledTextSegments([
       "fontSize",
@@ -112,7 +136,7 @@ export function createPluginNormalizer() {
       "fills",
       "boundVariables",
     ]);
-    const first = segments[0]!; // TODO: handle multiple segments
+    const first = segments[0]!;
 
     const textStyleKey =
       typeof node.textStyleId === "string"
@@ -124,8 +148,6 @@ export function createPluginNormalizer() {
       id: node.id,
       name: node.name,
       boundVariables: await normalizeBoundVariables(node),
-      layoutGrow: node.layoutGrow as 0 | 1 | undefined,
-      layoutAlign: node.layoutAlign,
       style: {
         fontSize: first.fontSize,
         fontWeight: first.fontWeight,
@@ -139,29 +161,20 @@ export function createPluginNormalizer() {
       },
       ...(textStyleKey ? { textStyleKey } : {}),
       characters: node.characters,
-      segments: node
-        .getStyledTextSegments([
-          "fontSize",
-          "fontWeight",
-          "fontName",
-          "letterSpacing",
-          "lineHeight",
-        ])
-        .map((segment) => ({
-          characters: segment.characters,
-          start: segment.start,
-          end: segment.end,
-          style: {
-            fontSize: segment.fontSize,
-            fontWeight: segment.fontWeight,
-            fontFamily: segment.fontName.family,
-            letterSpacing:
-              segment.letterSpacing.unit === "PIXELS" ? segment.letterSpacing.value : undefined,
-            lineHeightPx:
-              segment.lineHeight.unit === "PIXELS" ? segment.lineHeight.value : undefined,
-          },
-        })),
-      fills: normalizePaints(node.fills),
+      segments: segments.map((segment) => ({
+        characters: segment.characters,
+        start: segment.start,
+        end: segment.end,
+        style: {
+          fontSize: segment.fontSize,
+          fontWeight: segment.fontWeight,
+          fontFamily: segment.fontName.family,
+          letterSpacing:
+            segment.letterSpacing.unit === "PIXELS" ? segment.letterSpacing.value : undefined,
+          lineHeightPx: segment.lineHeight.unit === "PIXELS" ? segment.lineHeight.value : undefined,
+        },
+      })),
+      ...normalizeShapeProps(node),
     };
   }
 
@@ -173,7 +186,7 @@ export function createPluginNormalizer() {
       boundVariables: await normalizeBoundVariables(node),
       ...normalizeRadiusProps(node),
       ...normalizeAutolayoutProps(node),
-      children: await Promise.all(node.children.map(normalizeNode)),
+      children: await normalizeNodes(node.children),
     };
   }
 
@@ -203,7 +216,7 @@ export function createPluginNormalizer() {
       boundVariables: await normalizeBoundVariables(node),
       ...normalizeRadiusProps(node),
       ...normalizeAutolayoutProps(node),
-      children: await Promise.all(node.children.map(normalizeNode)),
+      children: await normalizeNodes(node.children),
       componentKey: mainComponent.key,
       componentSetKey:
         mainComponent.parent?.type === "COMPONENT_SET" ? mainComponent.parent.key : undefined,
@@ -283,6 +296,10 @@ export function createPluginNormalizer() {
       | "layoutSizingHorizontal"
       | "layoutSizingVertical"
       | "absoluteBoundingBox"
+      | "minHeight"
+      | "minWidth"
+      | "maxHeight"
+      | "maxWidth"
     > &
       Partial<Pick<FrameNode, "inferredAutoLayout">>,
   ) {
@@ -295,6 +312,10 @@ export function createPluginNormalizer() {
       fills: normalizePaints(node.fills),
       strokes: normalizePaints(node.strokes),
       strokeWeight: node.strokeWeight === figma.mixed ? undefined : node.strokeWeight,
+      minHeight: node.minHeight ?? undefined,
+      minWidth: node.minWidth ?? undefined,
+      maxHeight: node.maxHeight ?? undefined,
+      maxWidth: node.maxWidth ?? undefined,
     };
   }
 

package/src/normalizer/from-rest.ts

@@ -8,6 +8,7 @@ import type {
   NormalizedInstanceNode,
   NormalizedTextSegment,
   NormalizedVectorNode,
+  NormalizedBooleanOperationNode,
 } from "./types";
 
 export interface RestNormalizerContext {
@@ -17,6 +18,11 @@ export interface RestNormalizerContext {
 }
 
 export function createRestNormalizer(ctx: RestNormalizerContext) {
+  function normalizeNodes(nodes: readonly FigmaRestSpec.Node[]): NormalizedSceneNode[] {
+    // Figma REST API omits default values for some fields, "visible" is one of them
+    return nodes.filter((node) => !("visible" in node) || node.visible).map(normalizeNode);
+  }
+
   function normalizeNode(node: FigmaRestSpec.Node): NormalizedSceneNode {
     if (node.type === "FRAME") {
       return normalizeFrameNode(node);
@@ -30,6 +36,9 @@ export function createRestNormalizer(ctx: RestNormalizerContext) {
     if (node.type === "VECTOR") {
       return normalizeVectorNode(node);
     }
+    if (node.type === "BOOLEAN_OPERATION") {
+      return normalizeBooleanOperationNode(node);
+    }
     if (node.type === "TEXT") {
       return normalizeTextNode(node);
     }
@@ -40,13 +49,17 @@ export function createRestNormalizer(ctx: RestNormalizerContext) {
       return normalizeInstanceNode(node);
     }
 
-    throw new Error(`Unimplemented node type: ${node.type}, ${node.name}`);
+    return {
+      type: "UNHANDLED",
+      id: node.id,
+      original: node,
+    };
   }
 
   function normalizeFrameNode(node: FigmaRestSpec.FrameNode): NormalizedFrameNode {
     return {
       ...node,
-      children: node.children.map(normalizeNode),
+      children: normalizeNodes(node.children),
     };
   }
 
@@ -54,7 +67,7 @@ export function createRestNormalizer(ctx: RestNormalizerContext) {
     return {
       ...node,
       type: "FRAME",
-      children: node.children.map(normalizeNode),
+      children: normalizeNodes(node.children),
     };
   }
 
@@ -66,6 +79,15 @@ export function createRestNormalizer(ctx: RestNormalizerContext) {
     return node;
   }
 
+  function normalizeBooleanOperationNode(
+    node: FigmaRestSpec.BooleanOperationNode,
+  ): NormalizedBooleanOperationNode {
+    return {
+      ...node,
+      children: normalizeNodes(node.children),
+    };
+  }
+
   function normalizeTextNode(node: FigmaRestSpec.TextNode): NormalizedTextNode {
     // Function to segment a text node based on style overrides
     function segmentTextNode(textNode: FigmaRestSpec.TextNode): NormalizedTextSegment[] {
@@ -141,7 +163,7 @@ export function createRestNormalizer(ctx: RestNormalizerContext) {
   function normalizeComponentNode(node: FigmaRestSpec.ComponentNode): NormalizedComponentNode {
     return {
       ...node,
-      children: node.children.map(normalizeNode),
+      children: normalizeNodes(node.children),
     };
   }
 
@@ -167,7 +189,7 @@ export function createRestNormalizer(ctx: RestNormalizerContext) {
 
     return {
       ...node,
-      children: node.children.map(normalizeNode),
+      children: normalizeNodes(node.children),
       componentKey: mainComponent.key,
       componentSetKey: componentSet?.key,
       componentProperties,

package/src/normalizer/index.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export { createRestNormalizer } from "./from-rest";
+export { createPluginNormalizer } from "./from-plugin";

package/src/normalizer/types.ts

@@ -1,20 +1,40 @@
 import type * as FigmaRestSpec from "@figma/rest-api-spec";
 
-export type CommonProps = "type" | "id" | "name" | "boundVariables";
+export type NormalizedIsLayerTrait = Pick<
+  FigmaRestSpec.IsLayerTrait,
+  "type" | "id" | "name" | "boundVariables"
+>;
 
-export type RadiusProps = "cornerRadius" | "rectangleCornerRadii";
+export type NormalizedCornerTrait = Pick<
+  FigmaRestSpec.CornerTrait,
+  "cornerRadius" | "rectangleCornerRadii"
+>;
 
-export type ShapeProps =
-  | "layoutGrow"
+export type NormalizedHasChildrenTrait = {
+  children: NormalizedSceneNode[];
+};
+
+export type NormalizedHasLayoutTrait = Pick<
+  FigmaRestSpec.HasLayoutTrait,
   | "layoutAlign"
+  | "layoutGrow"
+  | "absoluteBoundingBox"
+  | "layoutPositioning"
   | "layoutSizingHorizontal"
   | "layoutSizingVertical"
-  | "absoluteBoundingBox"
-  | "fills"
-  | "strokes"
-  | "strokeWeight";
-
-export type LayoutProps =
+  | "minHeight"
+  | "minWidth"
+  | "maxHeight"
+  | "maxWidth"
+>;
+
+export type NormalizedHasGeometryTrait = Pick<
+  FigmaRestSpec.HasGeometryTrait,
+  "fills" | "strokes" | "strokeWeight" | "styles"
+>;
+
+export type NormalizedHasFramePropertiesTrait = Pick<
+  FigmaRestSpec.HasFramePropertiesTrait,
   | "layoutMode"
   | "layoutWrap"
   | "paddingLeft"
@@ -22,26 +42,43 @@ export type LayoutProps =
   | "paddingTop"
   | "paddingBottom"
   | "primaryAxisAlignItems"
-  | "counterAxisAlignItems"
   | "primaryAxisSizingMode"
+  | "counterAxisAlignItems"
   | "counterAxisSizingMode"
   | "itemSpacing"
-  | "counterAxisSpacing";
-
-export interface NormalizedFrameNode
-  extends Pick<FigmaRestSpec.FrameNode, CommonProps | ShapeProps | RadiusProps | LayoutProps> {
-  children: NormalizedSceneNode[];
+  | "counterAxisSpacing"
+>;
+
+export type NormalizedDefaultShapeTrait = NormalizedIsLayerTrait &
+  NormalizedHasLayoutTrait &
+  NormalizedHasGeometryTrait;
+
+export type NormalizedFrameTrait = NormalizedIsLayerTrait &
+  NormalizedHasLayoutTrait &
+  NormalizedHasGeometryTrait &
+  NormalizedHasChildrenTrait &
+  NormalizedCornerTrait &
+  NormalizedHasFramePropertiesTrait;
+
+export interface NormalizedFrameNode extends NormalizedFrameTrait {
+  type: FigmaRestSpec.FrameNode["type"];
 }
 
 export interface NormalizedRectangleNode
-  extends Pick<FigmaRestSpec.RectangleNode, CommonProps | ShapeProps | RadiusProps> {}
+  extends NormalizedDefaultShapeTrait,
+    NormalizedCornerTrait {
+  type: FigmaRestSpec.RectangleNode["type"];
+}
+
+export interface NormalizedTextNode extends NormalizedDefaultShapeTrait {
+  type: FigmaRestSpec.TextNode["type"];
+
+  style: FigmaRestSpec.TextNode["style"];
+
+  characters: FigmaRestSpec.TextNode["characters"];
 
-export interface NormalizedTextNode
-  extends Pick<
-    FigmaRestSpec.TextNode,
-    CommonProps | "layoutGrow" | "layoutAlign" | "style" | "characters" | "fills"
-  > {
   segments: NormalizedTextSegment[];
+
   textStyleKey?: string;
 }
 
@@ -60,13 +97,13 @@ export interface NormalizedTextSegment {
   };
 }
 
-export interface NormalizedComponentNode
-  extends Pick<FigmaRestSpec.ComponentNode, CommonProps | ShapeProps | RadiusProps | LayoutProps> {
-  children: NormalizedSceneNode[];
+export interface NormalizedComponentNode extends NormalizedFrameTrait {
+  type: FigmaRestSpec.ComponentNode["type"];
 }
 
-export interface NormalizedInstanceNode
-  extends Pick<FigmaRestSpec.InstanceNode, CommonProps | ShapeProps | RadiusProps | LayoutProps> {
+export interface NormalizedInstanceNode extends NormalizedFrameTrait {
+  type: FigmaRestSpec.InstanceNode["type"];
+
   componentProperties: {
     [key: string]: FigmaRestSpec.ComponentProperty & { componentKey?: string };
   };
@@ -78,11 +115,23 @@ export interface NormalizedInstanceNode
   children: NormalizedSceneNode[];
 }
 
-export interface NormalizedVectorNode
-  extends Pick<FigmaRestSpec.VectorNode, CommonProps | ShapeProps> {}
+export interface NormalizedVectorNode extends NormalizedDefaultShapeTrait, NormalizedCornerTrait {
+  type: FigmaRestSpec.VectorNode["type"];
+}
 
 export interface NormalizedBooleanOperationNode
-  extends Pick<FigmaRestSpec.BooleanOperationNode, CommonProps | "fills"> {}
+  extends NormalizedIsLayerTrait,
+    NormalizedHasChildrenTrait,
+    NormalizedHasLayoutTrait,
+    NormalizedHasGeometryTrait {
+  type: FigmaRestSpec.BooleanOperationNode["type"];
+}
+
+export interface NormalizedUnhandledNode {
+  type: "UNHANDLED";
+  id: string;
+  original: FigmaRestSpec.Node | SceneNode;
+}
 
 export type NormalizedSceneNode =
   | NormalizedFrameNode
@@ -91,4 +140,5 @@ export type NormalizedSceneNode =
   | NormalizedComponentNode
   | NormalizedInstanceNode
   | NormalizedVectorNode
-  | NormalizedBooleanOperationNode;
+  | NormalizedBooleanOperationNode
+  | NormalizedUnhandledNode;

package/src/utils/common.ts

@@ -0,0 +1,34 @@
+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]][];
+}
+
+/**
+ * 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,13 @@
+import type { RGBA } from "@figma/rest-api-spec";
+
+export function toCssPixel(value: number) {
+  return `${value}px`;
+}
+
+export function toCssRgba(color: RGBA) {
+  if (color.a === 1) {
+    return `rgb(${color.r * 255}, ${color.g * 255}, ${color.b * 255})`;
+  }
+
+  return `rgba(${color.r * 255}, ${color.g * 255}, ${color.b * 255}, ${color.a})`;
+}

package/src/{node-util.ts → utils/figma-node.ts}

@@ -1,4 +1,4 @@
-import type { NormalizedInstanceNode, NormalizedSceneNode } from "./normalizer/types";
+import type { NormalizedInstanceNode, NormalizedSceneNode } from "../normalizer";
 
 export function traverseNode(
   node: NormalizedSceneNode,

package/src/utils/figma-variable.ts

@@ -0,0 +1,13 @@
+export function isVariableAlias(value: unknown): value is VariableAlias {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "type" in value &&
+    value.type === "VARIABLE_ALIAS"
+  );
+}
+
+// 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]!;
+}

package/src/color.ts

@@ -1,78 +0,0 @@
-import type { NormalizedFrameNode, NormalizedTextNode } from "./normalizer/types";
-import { getColorVariableName } from "./variable";
-
-export function createBackgroundProps(
-  node: Pick<NormalizedFrameNode, "fills" | "boundVariables">,
-): Partial<Record<"background", string | undefined>> {
-  const fills = node.fills;
-  if (fills.length === 0) {
-    return {};
-  }
-
-  const fill = fills[0];
-  if (!fill || ("visible" in fill && !fill.visible) || fill.type !== "SOLID") {
-    return {};
-  }
-
-  if (node.boundVariables?.fills?.length === 1) {
-    return {
-      background: getColorVariableName(node.boundVariables.fills[0]!.id),
-    };
-  }
-
-  const color = fill.color;
-  return {
-    background: `rgba(${color.r * 255}, ${color.g * 255}, ${color.b * 255}, ${fill.opacity})`,
-  };
-}
-
-export function createColorProps(
-  node: Pick<NormalizedTextNode, "fills" | "boundVariables">,
-): Partial<Record<"color", string | undefined>> {
-  const fills = node.fills;
-  if (fills.length === 0) {
-    return {};
-  }
-
-  const fill = fills[0];
-  if (!fill || ("visible" in fill && !fill.visible) || fill.type !== "SOLID") {
-    return {};
-  }
-  if (node.boundVariables?.fills?.length === 1) {
-    return {
-      color: getColorVariableName(node.boundVariables.fills[0]!.id),
-    };
-  }
-
-  const color = fill.color;
-  return {
-    color: `rgba(${color.r * 255}, ${color.g * 255}, ${color.b * 255}, ${fill.opacity})`,
-  };
-}
-
-export function createBorderProps(
-  node: Pick<NormalizedFrameNode, "strokeWeight" | "strokes" | "boundVariables">,
-): Partial<Record<"borderWidth" | "borderColor", string | number | undefined>> {
-  const strokes = node.strokes;
-  if (strokes === undefined || strokes.length === 0) {
-    return {};
-  }
-
-  const stroke = strokes[0];
-  if (!stroke || ("visible" in stroke && !stroke.visible) || stroke.type !== "SOLID") {
-    return {};
-  }
-
-  if (node.boundVariables?.strokes?.length === 1) {
-    return {
-      borderWidth: node.strokeWeight as number,
-      borderColor: getColorVariableName(node.boundVariables.strokes[0]!.id),
-    };
-  }
-
-  const color = stroke.color;
-  return {
-    borderWidth: node.strokeWeight as number,
-    borderColor: `rgba(${color.r * 255}, ${color.g * 255}, ${color.b * 255}, ${stroke.opacity})`,
-  };
-}