figma-plugin-utilities 0.3.1 → 0.5.0

package/src/index.js

@@ -7,8 +7,17 @@ export {
   ListItem,
   LoadingState,
   PluginLayout,
+  Section,
   StatusBar,
+  DataTable,
   Header,
+  CodeExportModal,
+  FieldGrid,
+  LadderBadges,
+  SteppedField,
+  RampCurve,
+  MappingChip,
+  ConfirmModal,
 } from "./components/index.js";
 
 // Re-export all utilities
@@ -19,9 +28,14 @@ export {
   // Colors
   rgbToHex,
   hexToRgb,
+  isValidHex,
   getLuminance,
   getContrastRatio,
   meetsContrastLevel,
+  // Copy
+  plural,
+  UNDO,
+  joinList,
   // Validation
   validateUrl,
   validateJsonString,
@@ -38,12 +52,14 @@ export {
   withErrorHandling,
   safeAsync,
   parseJsonSafe,
-  notifyError,
-  notifySuccess,
-  notifyWarning,
   // Resize
   setDefaultWidth,
   getContentHeight,
   resizeToFit,
   autoResize,
+  // Confirmation dialogs
+  confirmAction,
+  confirmDiscardChanges,
+  answerConfirm,
+  confirmRequest,
 } from "./lib/index.js";

package/src/lib/colors.ts

@@ -0,0 +1,99 @@
+/**
+ * Color utilities for Figma plugins. No Figma API, so either thread may
+ * import them — but in a plugin that builds both threads in one pass, only
+ * one of them, or Vite splits this module into a chunk the sandbox can't load.
+ */
+
+/** A color with channels 0–1, as Figma's RGB and RGBA. */
+export type Rgb = { r: number; g: number; b: number; a?: number };
+
+export type HexOptions = {
+  /** Lowercase digits; uppercase by default */
+  lowercase?: boolean;
+  /** Prefix with "#"; true by default */
+  hash?: boolean;
+  /** Append the alpha byte when `a` is below 1 */
+  alpha?: boolean;
+};
+
+const byte = (channel: number) =>
+  Math.round(Math.min(1, Math.max(0, channel)) * 255)
+    .toString(16)
+    .padStart(2, "0");
+
+/**
+ * Convert an RGB color (0–1 channels, clamped) to a HEX string, "#FF0000" by
+ * default.
+ */
+export function rgbToHex(
+  { r, g, b, a }: Rgb,
+  { lowercase = false, hash = true, alpha = false }: HexOptions = {},
+): string {
+  let hex = byte(r) + byte(g) + byte(b);
+  if (alpha && a !== undefined && a < 1) hex += byte(a);
+  if (!lowercase) hex = hex.toUpperCase();
+  return hash ? `#${hex}` : hex;
+}
+
+/**
+ * Whether a string is a six-digit HEX color, in either case. The "#" is
+ * required unless `requireHash` is false.
+ */
+export function isValidHex(
+  value: string,
+  { requireHash = true }: { requireHash?: boolean } = {},
+): boolean {
+  return (requireHash ? /^#[0-9a-f]{6}$/i : /^#?[0-9a-f]{6}$/i).test(value);
+}
+
+/**
+ * Convert a HEX string ("#FF0000" or "FF0000") to an RGB color with 0–1
+ * channels, or null if it isn't six HEX digits.
+ */
+export function hexToRgb(
+  hex: string,
+): { r: number; g: number; b: number } | null {
+  const cleanHex = hex.replace(/^#/, "");
+  if (!/^[0-9A-Fa-f]{6}$/.test(cleanHex)) {
+    return null;
+  }
+  const r = parseInt(cleanHex.substring(0, 2), 16) / 255;
+  const g = parseInt(cleanHex.substring(2, 4), 16) / 255;
+  const b = parseInt(cleanHex.substring(4, 6), 16) / 255;
+  return { r, g, b };
+}
+
+/** Relative luminance of a color (0–1), for contrast calculations. */
+export function getLuminance({ r, g, b }: Rgb): number {
+  const adjust = (c: number) =>
+    c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+  return 0.2126 * adjust(r) + 0.7152 * adjust(g) + 0.0722 * adjust(b);
+}
+
+/** WCAG contrast ratio between two colors (1–21). */
+export function getContrastRatio(color1: Rgb, color2: Rgb): number {
+  const l1 = getLuminance(color1);
+  const l2 = getLuminance(color2);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/** Whether a contrast ratio meets a WCAG level. */
+export function meetsContrastLevel(
+  ratio: number,
+  level: "AA" | "AAA" | "AA-large" | "AAA-large",
+): boolean {
+  switch (level) {
+    case "AAA":
+      return ratio >= 7;
+    case "AAA-large":
+      return ratio >= 4.5;
+    case "AA":
+      return ratio >= 4.5;
+    case "AA-large":
+      return ratio >= 3;
+    default:
+      return false;
+  }
+}

package/src/lib/confirm.ts

@@ -0,0 +1,55 @@
+/**
+ * Confirmation dialogs, in place of the browser's confirm(): mount one
+ * ConfirmModal in the plugin's UI and it shows whatever confirmAction() asks.
+ */
+
+import { get, writable } from "svelte/store";
+
+export type ConfirmOptions = {
+  title: string;
+  message: string;
+  confirmLabel: string;
+  cancelLabel?: string;
+  destructive?: boolean;
+};
+
+type ConfirmRequest = ConfirmOptions & {
+  resolve: (confirmed: boolean) => void;
+};
+
+export const confirmRequest = writable<ConfirmRequest | null>(null);
+
+/**
+ * Ask the user to confirm. Resolves true on confirm; false on cancel,
+ * Escape, a click outside, or when another confirmation replaces this one.
+ */
+export function confirmAction(options: ConfirmOptions): Promise<boolean> {
+  get(confirmRequest)?.resolve(false);
+  return new Promise((resolve) => {
+    confirmRequest.set({ ...options, resolve });
+  });
+}
+
+/** Answer the open confirmation, if any */
+export function answerConfirm(confirmed: boolean): void {
+  const request = get(confirmRequest);
+  if (!request) return;
+  confirmRequest.set(null);
+  request.resolve(confirmed);
+}
+
+/**
+ * The prompt before unsaved edits are thrown away: closing a panel or
+ * leaving an editor. Resolves true to discard them.
+ */
+export function confirmDiscardChanges(
+  message = "Your changes haven't been saved.",
+): Promise<boolean> {
+  return confirmAction({
+    title: "Discard changes?",
+    message,
+    confirmLabel: "Discard changes",
+    cancelLabel: "Keep editing",
+    destructive: true,
+  });
+}

package/src/lib/errorHandling.js

@@ -145,42 +145,3 @@ export function parseJsonSafe(jsonString) {
     return { ok: false, error: message };
   }
 }
-
-/**
- * Show an error notification to the user with standardized options.
- * Use this in code.ts files for consistent error notifications.
- * @param {string} message - The error message to display
- * @param {unknown} [error] - Optional error object for logging
- * @param {string} [context] - Optional context for logging
- */
-export function notifyError(message, error, context) {
-  if (error) {
-    logError(error, context || message);
-  }
-  // @ts-ignore - figma global is available in plugin context
-  if (typeof figma !== "undefined") {
-    figma.notify(message, { error: true });
-  }
-}
-
-/**
- * Show a success notification to the user with standardized options.
- * @param {string} message - The success message to display
- */
-export function notifySuccess(message) {
-  // @ts-ignore - figma global is available in plugin context
-  if (typeof figma !== "undefined") {
-    figma.notify(message);
-  }
-}
-
-/**
- * Show a warning notification to the user.
- * @param {string} message - The warning message to display
- */
-export function notifyWarning(message) {
-  // @ts-ignore - figma global is available in plugin context
-  if (typeof figma !== "undefined") {
-    figma.notify(message, { timeout: 5000 });
-  }
-}

package/src/lib/figma-frame-builders.ts

@@ -0,0 +1,467 @@
+export type PaddingSpec =
+  number | { top?: number; right?: number; bottom?: number; left?: number };
+
+export type SpecTheme = {
+  cellFill: RGB;
+  cellBorder: RGB;
+  text: RGB;
+  chipBg: RGB;
+  headerFill: RGB;
+  subheaderFill: RGB;
+  headingText: RGB;
+  /** Bottom rule under the header; the inverse header has none. */
+  headerBorder?: RGB;
+};
+
+export type NodeKind = "frame" | "component";
+export type NodeFor<K extends NodeKind> = K extends "component"
+  ? ComponentNode
+  : FrameNode;
+
+function rgb(r: number, g: number, b: number): RGB {
+  return { r, g, b };
+}
+
+function createNode<K extends NodeKind>(as?: K): NodeFor<K> {
+  return (
+    as === "component" ? figma.createComponent() : figma.createFrame()
+  ) as NodeFor<K>;
+}
+
+function applyPadding(
+  frame: FrameNode | ComponentNode,
+  spec: PaddingSpec,
+): void {
+  if (typeof spec === "number") {
+    frame.paddingTop = spec;
+    frame.paddingRight = spec;
+    frame.paddingBottom = spec;
+    frame.paddingLeft = spec;
+  } else {
+    frame.paddingTop = spec.top ?? 0;
+    frame.paddingRight = spec.right ?? 0;
+    frame.paddingBottom = spec.bottom ?? 0;
+    frame.paddingLeft = spec.left ?? 0;
+  }
+}
+
+export const specTokens = {
+  accentColors: {
+    green: rgb(0.251, 0.769, 0.349), // #40C459 — AAA
+    blue: rgb(0.447, 0.682, 0.988), // #72AEFC — AA
+    purple: rgb(0.753, 0.608, 0.965), // #C09BF6 — AA18
+    red: rgb(0.98, 0.553, 0.569), // #FA8D91 — DNP
+  },
+  fonts: {
+    body: { family: "Inter", style: "Regular", size: 14 },
+    bodyBold: { family: "Inter", style: "Semi Bold", size: 14 },
+    subheading: { family: "Inter", style: "Medium", size: 24 },
+    heading: { family: "Inter", style: "Medium", size: 48 },
+    code: { family: "IBM Plex Mono", style: "Regular", size: 12 },
+  },
+  themes: {
+    light: {
+      cellFill: rgb(1.0, 1.0, 1.0), // #FFFFFF
+      cellBorder: rgb(0.949, 0.949, 0.949), // #F2F2F2
+      text: rgb(0.09, 0.09, 0.09), // #171717
+      chipBg: rgb(0.949, 0.949, 0.949), // #F2F2F2
+      headerFill: rgb(1.0, 1.0, 1.0), // #FFFFFF
+      subheaderFill: rgb(0.949, 0.949, 0.949), // #F2F2F2
+      headingText: rgb(0.09, 0.09, 0.09), // #171717
+      headerBorder: rgb(0.886, 0.886, 0.886), // #E2E2E2
+    } satisfies SpecTheme,
+    dark: {
+      cellFill: rgb(0.09, 0.09, 0.09), // #171717
+      cellBorder: rgb(0.114, 0.114, 0.114), // #1D1D1D
+      text: rgb(1.0, 1.0, 1.0), // #FFFFFF
+      chipBg: rgb(0.157, 0.157, 0.157), // #282828
+      headerFill: rgb(0.09, 0.09, 0.09), // #171717
+      subheaderFill: rgb(0.157, 0.157, 0.157), // #282828
+      headingText: rgb(1.0, 1.0, 1.0), // #FFFFFF
+    } satisfies SpecTheme,
+  },
+};
+
+export async function loadSpecFonts(): Promise<void> {
+  await Promise.all([
+    figma.loadFontAsync({ family: "Inter", style: "Regular" }),
+    figma.loadFontAsync({ family: "Inter", style: "Semi Bold" }),
+    figma.loadFontAsync({ family: "Inter", style: "Medium" }),
+    figma.loadFontAsync({ family: "IBM Plex Mono", style: "Regular" }),
+  ]);
+}
+
+type AutoLayoutOpts = {
+  name: string;
+  direction: "HORIZONTAL" | "VERTICAL" | "NONE";
+  spacing?: number;
+  padding?: PaddingSpec;
+  fill?: RGB;
+  cornerRadius?: number;
+  width?: number;
+  height?: number;
+  clipsContent?: boolean;
+  border?: { color: RGB; width?: number };
+};
+
+function applyAutoLayout(
+  node: FrameNode | ComponentNode,
+  opts: AutoLayoutOpts,
+): void {
+  node.name = opts.name;
+  node.layoutMode = opts.direction;
+  node.fills = opts.fill ? [{ type: "SOLID", color: opts.fill }] : [];
+
+  if (opts.cornerRadius !== undefined) node.cornerRadius = opts.cornerRadius;
+  if (opts.clipsContent !== undefined) node.clipsContent = opts.clipsContent;
+  if (opts.padding !== undefined) applyPadding(node, opts.padding);
+
+  if (opts.direction !== "NONE") {
+    node.itemSpacing = opts.spacing ?? 0;
+    const isHorizontal = opts.direction === "HORIZONTAL";
+    node.primaryAxisSizingMode =
+      (isHorizontal ? opts.width : opts.height) !== undefined
+        ? "FIXED"
+        : "AUTO";
+    node.counterAxisSizingMode =
+      (isHorizontal ? opts.height : opts.width) !== undefined
+        ? "FIXED"
+        : "AUTO";
+  }
+
+  if (opts.width !== undefined || opts.height !== undefined) {
+    node.resize(opts.width ?? node.width, opts.height ?? node.height);
+  }
+
+  if (opts.border) {
+    node.strokes = [{ type: "SOLID", color: opts.border.color }];
+    node.strokeWeight = opts.border.width ?? 1;
+    node.strokeAlign = "CENTER";
+  }
+}
+
+export function createAutoLayoutFrame(opts: AutoLayoutOpts): FrameNode {
+  const frame = figma.createFrame();
+  applyAutoLayout(frame, opts);
+  return frame;
+}
+
+export function createAutoLayoutComponent(opts: AutoLayoutOpts): ComponentNode {
+  const component = figma.createComponent();
+  applyAutoLayout(component, opts);
+  return component;
+}
+
+export function createText(opts: {
+  characters: string;
+  font: { family: string; style: string; size: number };
+  color?: RGB;
+  lineHeight?: number;
+  letterSpacing?: number;
+  width?: number;
+}): TextNode {
+  const node = figma.createText();
+  node.fontName = { family: opts.font.family, style: opts.font.style };
+  node.fontSize = opts.font.size;
+
+  if (opts.lineHeight !== undefined) {
+    node.lineHeight = { value: opts.lineHeight * 100, unit: "PERCENT" };
+  }
+  if (opts.letterSpacing !== undefined) {
+    node.letterSpacing = { value: opts.letterSpacing, unit: "PIXELS" };
+  }
+
+  node.characters = opts.characters;
+  node.fills = [
+    { type: "SOLID", color: opts.color ?? specTokens.themes.light.text },
+  ];
+
+  if (opts.width !== undefined) {
+    node.textAutoResize = "HEIGHT";
+    node.resize(opts.width, node.height);
+  }
+
+  return node;
+}
+
+export function createTokenChip<K extends NodeKind = "frame">(opts: {
+  label: string;
+  background: RGB;
+  textColor?: RGB;
+  width?: number;
+  as?: K;
+}): NodeFor<K> {
+  const node = createNode(opts.as);
+  applyAutoLayout(node, {
+    name: "label",
+    direction: "VERTICAL",
+    padding: { right: 6, left: 6 },
+    fill: opts.background,
+    cornerRadius: 2,
+    height: 24,
+    width: opts.width,
+  });
+  node.primaryAxisAlignItems = "CENTER";
+  const text = createText({
+    characters: opts.label,
+    font: specTokens.fonts.code,
+    color: opts.textColor ?? specTokens.themes.light.text,
+    lineHeight: 1.4,
+    letterSpacing: 0.18,
+  });
+  text.name = "label";
+  text.textAutoResize = "WIDTH_AND_HEIGHT";
+  node.appendChild(text);
+  return node as NodeFor<K>;
+}
+
+export function createColorSwatch<K extends NodeKind = "frame">(opts: {
+  color: RGB;
+  size?: number;
+  cornerRadius?: number;
+  inverse?: boolean;
+  as?: K;
+}): NodeFor<K> {
+  const size = opts.size ?? 40;
+  const node = createNode(opts.as);
+  applyAutoLayout(node, {
+    name: "swatch",
+    direction: "NONE",
+    fill: opts.color,
+    cornerRadius: opts.cornerRadius ?? 2,
+    width: size,
+    height: size,
+  });
+  node.strokes = [
+    {
+      type: "SOLID",
+      color: opts.inverse ? rgb(1, 1, 1) : rgb(0, 0, 0),
+      opacity: 0.1,
+    },
+  ];
+  node.strokeWeight = 1;
+  node.strokeAlign = "INSIDE";
+  return node as NodeFor<K>;
+}
+
+function chipOrInstance(
+  source: ComponentNode | undefined,
+  label: string,
+  background: RGB,
+  textColor: RGB,
+): FrameNode | InstanceNode {
+  if (source) return source.createInstance();
+  return createTokenChip({ label, background, textColor });
+}
+
+// The library cell holds its chips in a "tokens" slot, a hugging row.
+function tokensRow(chip: FrameNode | InstanceNode): FrameNode {
+  const row = createAutoLayoutFrame({
+    name: "tokens",
+    direction: "HORIZONTAL",
+    spacing: 4,
+  });
+  row.appendChild(chip);
+  return row;
+}
+
+function swatchOrInstance(
+  source: ComponentNode | undefined,
+  color: RGB,
+  inverse: boolean,
+): FrameNode | InstanceNode {
+  if (source) return source.createInstance();
+  return createColorSwatch({ color, inverse });
+}
+
+export function createTableCell<K extends NodeKind = "frame">(opts: {
+  variant: "text" | "header" | "token";
+  theme?: SpecTheme;
+  swatch?: boolean;
+  text?: string;
+  chipLabel?: string;
+  chipBackground?: RGB;
+  swatchColor?: RGB;
+  chipSource?: ComponentNode;
+  swatchSource?: ComponentNode;
+  width?: number;
+  height?: number;
+  textSizing?: "fill" | "hug";
+  as?: K;
+}): NodeFor<K> {
+  const theme = opts.theme ?? specTokens.themes.light;
+  const border = { color: theme.cellBorder };
+  const isTokenSwatch = opts.variant === "token" && opts.swatch;
+
+  if (isTokenSwatch) {
+    const node = createNode(opts.as);
+    applyAutoLayout(node, {
+      name: "table-cell",
+      direction: "HORIZONTAL",
+      padding: { top: 12, right: 20, bottom: 12, left: 20 },
+      fill: theme.cellFill,
+      width: opts.width ?? 240,
+      height: opts.height ?? 72,
+      border,
+    });
+    node.primaryAxisAlignItems = "SPACE_BETWEEN";
+    node.counterAxisAlignItems = "MIN";
+    node.appendChild(
+      tokensRow(
+        chipOrInstance(
+          opts.chipSource,
+          opts.chipLabel ?? "",
+          opts.chipBackground ?? theme.chipBg,
+          theme.text,
+        ),
+      ),
+    );
+    node.appendChild(
+      swatchOrInstance(
+        opts.swatchSource,
+        opts.swatchColor ?? rgb(0, 0, 0),
+        theme.cellFill.r < 0.5,
+      ),
+    );
+    return node as NodeFor<K>;
+  }
+
+  const isTextSwatch = opts.variant === "text" && opts.swatch;
+  const defaultHeight = isTextSwatch ? 72 : 56;
+
+  const node = createNode(opts.as);
+  applyAutoLayout(node, {
+    name: "table-cell",
+    direction: "HORIZONTAL",
+    spacing: opts.variant === "token" ? 8 : isTextSwatch ? 16 : 0,
+    padding: { top: 12, right: 20, bottom: 16, left: 20 },
+    fill: theme.cellFill,
+    width: opts.width ?? 240,
+    height: opts.height ?? defaultHeight,
+    border,
+  });
+
+  if (isTextSwatch) {
+    node.primaryAxisAlignItems = "SPACE_BETWEEN";
+    node.counterAxisAlignItems = "MIN";
+    const label = createText({
+      characters: opts.text ?? "",
+      font: specTokens.fonts.body,
+      color: theme.text,
+      lineHeight: 1.4,
+      width: 144,
+    });
+    label.name = "text";
+    node.appendChild(label);
+    node.appendChild(
+      swatchOrInstance(
+        opts.swatchSource,
+        opts.swatchColor ?? rgb(0, 0, 0),
+        theme.cellFill.r < 0.5,
+      ),
+    );
+    return node as NodeFor<K>;
+  }
+
+  if (opts.variant === "token") {
+    node.appendChild(
+      tokensRow(
+        chipOrInstance(
+          opts.chipSource,
+          opts.chipLabel ?? "",
+          opts.chipBackground ?? theme.chipBg,
+          theme.text,
+        ),
+      ),
+    );
+    return node as NodeFor<K>;
+  }
+
+  // "text" and "header" variants
+  const isBold = opts.variant === "header";
+  const label = createText({
+    characters: opts.text ?? "",
+    font: isBold ? specTokens.fonts.bodyBold : specTokens.fonts.body,
+    color: theme.text,
+    lineHeight: 1.4,
+  });
+  label.name = "text";
+  if (opts.textSizing === "hug") {
+    label.textAutoResize = "WIDTH_AND_HEIGHT";
+  } else {
+    label.layoutGrow = 1;
+    label.textAutoResize = "HEIGHT";
+  }
+  node.appendChild(label);
+
+  return node as NodeFor<K>;
+}
+
+export function createTableHeader<K extends NodeKind = "frame">(opts: {
+  variant: "header" | "subheader";
+  theme?: SpecTheme;
+  title?: string;
+  width?: number;
+  height?: number;
+  as?: K;
+}): NodeFor<K> {
+  const theme = opts.theme ?? specTokens.themes.light;
+  const title = opts.title ?? "";
+
+  if (opts.variant === "header") {
+    const node = createNode(opts.as);
+    applyAutoLayout(node, {
+      name: "table-header",
+      direction: "VERTICAL",
+      padding: { top: 16, right: 20, bottom: 16, left: 20 },
+      width: opts.width ?? 960,
+      height: opts.height ?? 160,
+      fill: theme.headerFill,
+    });
+    if (theme.headerBorder) {
+      node.strokes = [{ type: "SOLID", color: theme.headerBorder }];
+      node.strokeTopWeight = 0;
+      node.strokeRightWeight = 0;
+      node.strokeBottomWeight = 1;
+      node.strokeLeftWeight = 0;
+      node.strokeAlign = "INSIDE";
+    }
+    const text = createText({
+      characters: title,
+      font: specTokens.fonts.heading,
+      color: theme.headingText,
+      lineHeight: 1,
+      letterSpacing: -1.92,
+    });
+    text.name = "title";
+    node.appendChild(text);
+    text.layoutSizingHorizontal = "FILL";
+    text.textAutoResize = "HEIGHT";
+    return node as NodeFor<K>;
+  }
+
+  // subheader: the title sits on the bottom edge
+  const node = createNode(opts.as);
+  applyAutoLayout(node, {
+    name: "table-subheader",
+    direction: "VERTICAL",
+    spacing: 8,
+    padding: { top: 16, right: 20, bottom: 16, left: 20 },
+    fill: theme.subheaderFill,
+    width: opts.width ?? 960,
+    height: opts.height ?? 96,
+  });
+  node.primaryAxisAlignItems = "MAX";
+  const text = createText({
+    characters: title,
+    font: specTokens.fonts.subheading,
+    color: theme.headingText,
+    lineHeight: 1.3,
+    letterSpacing: -0.48,
+  });
+  text.name = "title";
+  node.appendChild(text);
+  text.layoutSizingHorizontal = "FILL";
+  text.textAutoResize = "HEIGHT";
+  return node as NodeFor<K>;
+}