figma-plugin-utilities 0.4.0 → 0.5.1

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

@@ -47,7 +47,7 @@ function applyPadding(
 
 export const specTokens = {
   accentColors: {
-    green: rgb(0.337, 0.757, 0.396), // #56C165 — AAA
+    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
@@ -195,7 +195,7 @@ export function createTokenChip<K extends NodeKind = "frame">(opts: {
   applyAutoLayout(node, {
     name: "label",
     direction: "VERTICAL",
-    padding: { right: 4, left: 4 },
+    padding: { right: 6, left: 6 },
     fill: opts.background,
     cornerRadius: 2,
     height: 24,

package/src/lib/figma-helpers.ts

@@ -18,56 +18,43 @@ export function sendToUI<T extends Record<string, unknown>>(
   }
 }
 
-/**
- * Get all local variable collections
- * @returns Promise resolving to array of variable collections
- */
-export async function getCollections(): Promise<VariableCollection[]> {
-  return figma.variables.getLocalVariableCollectionsAsync();
-}
-
-/**
- * Get all local variables of a specific type
- * @param type - Variable type to filter by
- * @returns Promise resolving to array of variables
- */
-export async function getVariables(
-  type?: VariableResolvedDataType,
-): Promise<Variable[]> {
-  return figma.variables.getLocalVariablesAsync(type);
-}
+// Long enough to read: about 60ms a character, and never under `minimum`.
+const readingTime = (message: string, minimum: number) =>
+  Math.max(minimum, message.length * 60);
 
 /**
- * Show an error notification to the user
- * @param message - Error message to display
- * @param timeout - How long to show the notification (ms)
+ * Show an error notification: something failed, or the file needs fixing
+ * @param message - What went wrong, then what to do
+ * @param timeout - How long to show it (ms); by default long enough to read,
+ *   5s at least
  */
-export function showError(message: string, timeout = 5000): void {
-  figma.notify(message, { error: true, timeout });
+export function showError(message: string, timeout?: number): void {
+  figma.notify(message, {
+    error: true,
+    timeout: timeout ?? readingTime(message, 5000),
+  });
 }
 
 /**
- * Show a success notification to the user
- * @param message - Success message to display
- * @param timeout - How long to show the notification (ms)
+ * Show a success notification: the change is made. End a change to the file
+ * with `UNDO` from `lib/format`.
+ * @param message - What changed, with a count
+ * @param timeout - How long to show it (ms); by default long enough to read,
+ *   3s at least
  */
-export function showSuccess(message: string, timeout = 3000): void {
-  figma.notify(message, { timeout });
+export function showSuccess(message: string, timeout?: number): void {
+  figma.notify(message, { timeout: timeout ?? readingTime(message, 3000) });
 }
 
 /**
- * Get the current selection, optionally filtered by type
- * @param nodeType - Optional node type to filter by
- * @returns Array of selected nodes
+ * Show a regular notification for a run with nothing to do: an empty
+ * selection, nothing to change. Not an error; say what to select or set.
+ * @param message - Why nothing happened, then what to do
+ * @param timeout - How long to show it (ms); by default long enough to read,
+ *   4s at least
  */
-export function getSelection<T extends SceneNode>(
-  nodeType?: NodeType,
-): readonly T[] {
-  const selection = figma.currentPage.selection;
-  if (nodeType) {
-    return selection.filter((node) => node.type === nodeType) as T[];
-  }
-  return selection as readonly T[];
+export function showNotice(message: string, timeout?: number): void {
+  figma.notify(message, { timeout: timeout ?? readingTime(message, 4000) });
 }
 
 /**
@@ -85,35 +72,92 @@ export function focusNodes(nodes: readonly SceneNode[]): void {
  * @param family - Font family name
  * @param style - Font style (e.g., "Regular", "Bold")
  */
-export async function loadFont(family: string, style: string): Promise<void> {
-  await figma.loadFontAsync({ family, style });
+export function loadFont(family: string, style: string): Promise<void> {
+  return loadFontOnce({ family, style });
 }
 
 /**
- * Save data to client storage (persists across sessions)
- * @param key - Storage key
- * @param value - Value to store (must be JSON-serializable)
+ * Every font a text node uses: its own when uniform, each run's when mixed.
  */
-export async function saveToStorage<T>(key: string, value: T): Promise<void> {
-  await figma.clientStorage.setAsync(key, value);
+export function fontsOf(node: TextNode): FontName[] {
+  if (node.fontName !== figma.mixed) return [node.fontName];
+  return node.characters.length > 0
+    ? node.getRangeAllFontNames(0, node.characters.length)
+    : [];
 }
 
+const fontLoads = new Map<string, Promise<void>>();
+
 /**
- * Load data from client storage
- * @param key - Storage key
- * @param defaultValue - Default value if key doesn't exist
- * @returns Stored value or default
+ * Load a font once per plugin run: later calls for it share the first load,
+ * so hundreds of text layers wait once per font rather than a round trip
+ * each. A load that fails is forgotten, so the next call tries again.
  */
-export async function loadFromStorage<T>(
-  key: string,
-  defaultValue?: T,
-): Promise<T | undefined> {
-  try {
-    const value = await figma.clientStorage.getAsync(key);
-    return value !== undefined ? value : defaultValue;
-  } catch {
-    return defaultValue;
+export function loadFontOnce(font: FontName): Promise<void> {
+  const key = `${font.family}\u0000${font.style}`;
+  let load = fontLoads.get(key);
+  if (!load) {
+    load = figma.loadFontAsync(font).catch((error: unknown) => {
+      fontLoads.delete(key);
+      throw error;
+    });
+    fontLoads.set(key, load);
   }
+  return load;
+}
+
+/**
+ * Load every font a text node uses, each once per run — Figma refuses to
+ * write to text whose fonts aren't loaded. Rejects when one won't load, as a
+ * missing font doesn't.
+ */
+export async function loadNodeFonts(node: TextNode): Promise<void> {
+  await Promise.all(fontsOf(node).map(loadFontOnce));
+}
+
+/**
+ * Set a text node's characters in its own fonts, loading them first. Rejects,
+ * leaving the text as it was, when one of its fonts won't load.
+ */
+export async function setText(
+  node: TextNode,
+  characters: string,
+): Promise<void> {
+  await loadNodeFonts(node);
+  node.characters = characters;
+}
+
+/**
+ * Settings kept in clientStorage under `key`, cleaned by one `sanitize` on
+ * the way in and on the way out, so what's saved is always what a load would
+ * accept. `sanitize` takes anything — a value an older version stored, a
+ * message from the UI, undefined on first run — and returns complete
+ * settings. `save` resolves to the settings it stored. Storage errors are
+ * logged, not thrown: a load falls back to `sanitize(undefined)`.
+ */
+export function createSettingsStore<T>(
+  key: string,
+  sanitize: (raw: unknown) => T,
+): { load(): Promise<T>; save(raw: unknown): Promise<T> } {
+  return {
+    async load() {
+      try {
+        return sanitize(await figma.clientStorage.getAsync(key));
+      } catch (error) {
+        console.error(`Couldn't read "${key}" from clientStorage:`, error);
+        return sanitize(undefined);
+      }
+    },
+    async save(raw) {
+      const settings = sanitize(raw);
+      try {
+        await figma.clientStorage.setAsync(key, settings);
+      } catch (error) {
+        console.error(`Couldn't save "${key}" to clientStorage:`, error);
+      }
+      return settings;
+    },
+  };
 }
 
 /**

package/src/lib/figma-variables.ts

@@ -0,0 +1,151 @@
+/**
+ * Variable helpers for plugin code (code.ts): alias and color guards, and a
+ * variable's value through any aliases.
+ */
+
+/** Whether a variable value is an alias to another variable. */
+export function isVariableAlias(value: unknown): value is VariableAlias {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as VariableAlias).type === "VARIABLE_ALIAS"
+  );
+}
+
+/** Whether a variable value is a color, RGB or RGBA with 0–1 channels. */
+export function isColorValue(value: unknown): value is RGB | RGBA {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as RGB).r === "number" &&
+    typeof (value as RGB).g === "number" &&
+    typeof (value as RGB).b === "number"
+  );
+}
+
+/** A color value as RGBA, alpha 1 where it has none, or null for anything else. */
+export function toRgba(value: unknown): RGBA | null {
+  return isColorValue(value) ? { a: 1, ...value } : null;
+}
+
+/** The file's local variables and collections by id, read once for many lookups. */
+export interface VariableLookup {
+  variables: Map<string, Variable>;
+  collections: Map<string, VariableCollection>;
+}
+
+export async function getVariableLookup(): Promise<VariableLookup> {
+  const [variables, collections] = await Promise.all([
+    figma.variables.getLocalVariablesAsync(),
+    figma.variables.getLocalVariableCollectionsAsync(),
+  ]);
+  return {
+    variables: new Map(variables.map((v): [string, Variable] => [v.id, v])),
+    collections: new Map(
+      collections.map((c): [string, VariableCollection] => [c.id, c]),
+    ),
+  };
+}
+
+// A variable's value at a mode, or at its collection's default mode where it
+// has none there (null asks for the default).
+function valueAt(
+  variable: Variable,
+  modeId: string | null,
+  collection: VariableCollection | null | undefined,
+): VariableValue | undefined {
+  return (
+    (modeId !== null ? variable.valuesByMode[modeId] : undefined) ??
+    (collection
+      ? variable.valuesByMode[collection.defaultModeId]
+      : undefined) ??
+    Object.values(variable.valuesByMode)[0]
+  );
+}
+
+// The mode to read an alias's target at: the same mode where its collection
+// has it (an alias within one collection), else the default.
+const modeIn = (
+  modeId: string | null,
+  collection: VariableCollection | null | undefined,
+): string | null =>
+  modeId !== null && collection?.modes.some((m) => m.modeId === modeId)
+    ? modeId
+    : null;
+
+/**
+ * A variable's value at a mode (null for its collection's default), following
+ * aliases to a value that isn't one. Each variable down the chain is read at
+ * the same mode where its collection has it, else at its default mode. Given
+ * an alias, starts at its target. Local variables only, from `lookup`; null
+ * where the chain leaves the file or runs past `maxDepth`.
+ */
+export function resolveVariableValue(
+  start: Variable | VariableAlias,
+  modeId: string | null,
+  lookup: VariableLookup,
+  maxDepth = 10,
+): VariableValue | null {
+  let variable: Variable | undefined;
+  let mode = modeId;
+  if (isVariableAlias(start)) {
+    variable = lookup.variables.get(start.id);
+    if (!variable) return null;
+    mode = modeIn(mode, lookup.collections.get(variable.variableCollectionId));
+  } else {
+    variable = start;
+  }
+  for (let depth = 0; depth <= maxDepth; depth++) {
+    const raw = valueAt(
+      variable,
+      mode,
+      lookup.collections.get(variable.variableCollectionId),
+    );
+    if (!isVariableAlias(raw)) return raw ?? null;
+    const target: Variable | undefined = lookup.variables.get(raw.id);
+    if (!target) return null;
+    mode = modeIn(mode, lookup.collections.get(target.variableCollectionId));
+    variable = target;
+  }
+  return null;
+}
+
+/**
+ * As `resolveVariableValue`, but follows aliases into enabled libraries too,
+ * fetching any variable or collection `lookup` doesn't have (or every one,
+ * without a lookup).
+ */
+export async function resolveVariableValueAsync(
+  start: Variable | VariableAlias,
+  modeId: string | null,
+  lookup?: VariableLookup,
+  maxDepth = 10,
+): Promise<VariableValue | null> {
+  const variableById = async (id: string) =>
+    lookup?.variables.get(id) ??
+    (await figma.variables.getVariableByIdAsync(id));
+  const collectionOf = async (v: Variable) =>
+    lookup?.collections.get(v.variableCollectionId) ??
+    (await figma.variables.getVariableCollectionByIdAsync(
+      v.variableCollectionId,
+    ));
+
+  let variable: Variable | null;
+  let mode = modeId;
+  if (isVariableAlias(start)) {
+    variable = await variableById(start.id);
+    if (!variable) return null;
+    mode = modeIn(mode, await collectionOf(variable));
+  } else {
+    variable = start;
+  }
+  for (let depth = 0; depth <= maxDepth; depth++) {
+    const raw = valueAt(variable, mode, await collectionOf(variable));
+    if (!isVariableAlias(raw)) return raw ?? null;
+    const target: Variable | null = await variableById(raw.id);
+    if (!target) return null;
+    mode = modeIn(mode, await collectionOf(target));
+    variable = target;
+  }
+  return null;
+}

package/src/lib/format.ts

@@ -0,0 +1,19 @@
+/**
+ * Copy helpers with no Figma API, for either thread.
+ */
+
+/** "1 layer", "3 layers"; `pluralForm` for the irregular ones: "2 entries" */
+export const plural = (
+  count: number,
+  singular: string,
+  pluralForm = `${singular}s`,
+): string => `${count} ${count === 1 ? singular : pluralForm}`;
+
+/** "a", "a and b", "a, b and c"; `conjunction` replaces "and" */
+export const joinList = (items: string[], conjunction = "and"): string =>
+  items.length <= 1
+    ? (items[0] ?? "")
+    : `${items.slice(0, -1).join(", ")} ${conjunction} ${items[items.length - 1]}`;
+
+/** The last sentence of a success notification for a change to the file. */
+export const UNDO = "Press Ctrl/Cmd+Z to undo.";

package/src/lib/index.js

@@ -5,10 +5,14 @@ export { sendToPlugin, createMessageHandler } from "./messages.js";
 export {
   rgbToHex,
   hexToRgb,
+  isValidHex,
   getLuminance,
   getContrastRatio,
   meetsContrastLevel,
-} from "./colors.js";
+} from "./colors.ts";
+
+// Copy helpers
+export { plural, joinList, UNDO } from "./format.ts";
 
 // Validation utilities
 export {
@@ -30,9 +34,6 @@ export {
   withErrorHandling,
   safeAsync,
   parseJsonSafe,
-  notifyError,
-  notifySuccess,
-  notifyWarning,
 } from "./errorHandling.js";
 
 // Resize utilities
@@ -42,3 +43,11 @@ export {
   resizeToFit,
   autoResize,
 } from "./resize.js";
+
+// Confirmation dialogs, shown by ConfirmModal
+export {
+  confirmAction,
+  confirmDiscardChanges,
+  answerConfirm,
+  confirmRequest,
+} from "./confirm.ts";