figma-plugin-utilities 0.3.1 → 0.5.0

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";

package/src/lib/scale.ts

@@ -0,0 +1,147 @@
+// Responsive scale math shared by plugins that shape a scale across
+// breakpoints, such as Vitrine Tools' Type and Spacing tabs: the ramp's quadratic
+// Bézier, blending by viewport width, values between breakpoints, fallback
+// widths and fluid CSS. Pure — no Figma API — so both threads may import it.
+//
+// Units are the caller's: the Type tab works in px along its ladder, the
+// Spacing tab in ladder rungs. Nothing here maps a value onto a ladder.
+
+/** The quadratic Bézier through p0 and p2, pulled toward p1, at t in 0…1. */
+export const bezier = (t: number, p0: number, p1: number, p2: number) =>
+  (1 - t) ** 2 * p0 + 2 * (1 - t) * t * p1 + t * t * p2;
+
+/** How far the bend may move toward either end; at 0 or 1 the curve folds. */
+export const clampPosition = (c: number) => Math.min(0.98, Math.max(0.02, c));
+
+/**
+ * The curve's parameter t for a point at x, 0…1, when the bend sits at `c`
+ * along x: the curve runs through x(t) = 2(1−t)t·c + t², solved for t in the
+ * conjugate form, which has no division by zero at c = 0.5 (where t = x).
+ */
+export function levelT(x: number, c = 0.5): number {
+  const pos = clampPosition(c);
+  return x / (Math.sqrt(pos * pos + (1 - 2 * pos) * x) + pos);
+}
+
+export const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
+
+/**
+ * Rounds halves down, so a growing value holds its smaller size a breakpoint
+ * longer — 16 16 18 18 20 rather than 16 18 18 20 20.
+ */
+export const roundHalfDown = (x: number) => Math.ceil(x - 0.5);
+
+/**
+ * How far breakpoint `index` sits from the smallest toward the largest, 0…1:
+ * by viewport width when every width is known and they widen, so the blend
+ * matches CSS vw, and evenly by position otherwise.
+ */
+export function blendAt(
+  index: number,
+  count: number,
+  widths?: number[],
+): number {
+  if (count < 2) return 0;
+  const w0 = widths?.[0];
+  const w1 = widths?.[count - 1];
+  if (
+    widths?.length === count &&
+    w0 !== undefined &&
+    w1 !== undefined &&
+    w1 > w0
+  ) {
+    return Math.min(1, Math.max(0, (widths[index] - w0) / (w1 - w0)));
+  }
+  return index / (count - 1);
+}
+
+/**
+ * A value at viewport width `width`, from its value at each breakpoint:
+ * straight between the breakpoints either side, as fluid CSS has it, and
+ * held beyond the smallest and largest. Stepped, it is the value of the last
+ * breakpoint at or below the width, as a media query holds it.
+ */
+export function valueAtWidth(
+  widths: number[],
+  values: number[],
+  width: number,
+  stepped = false,
+): number {
+  const last = widths.length - 1;
+  if (last < 0) return 0;
+  if (width <= widths[0]) return values[0];
+  if (width >= widths[last]) return values[last];
+  let b = 0;
+  while (b < last - 1 && widths[b + 1] <= width) b++;
+  if (stepped) return values[b];
+  const t = (width - widths[b]) / (widths[b + 1] - widths[b]);
+  return values[b] + (values[b + 1] - values[b]) * t;
+}
+
+/** Breakpoint widths by name, for a file that doesn't give them. */
+export const FALLBACK_WIDTHS: Record<string, number> = {
+  xs: 320,
+  sm: 400,
+  md: 768,
+  lg: 1024,
+  xl: 1440,
+  xlg: 1440,
+  "2xl": 1920,
+  xxl: 1920,
+  "3xl": 2560,
+  xxxl: 2560,
+  max: 2560,
+};
+
+/** Whether a name is one the fallback widths know, in any case. */
+export const isBreakpointName = (name: string) =>
+  Object.prototype.hasOwnProperty.call(FALLBACK_WIDTHS, name.toLowerCase());
+
+/**
+ * Each breakpoint's width: the file's (`known`), else the usual one for its
+ * name, else 400px past the one before. Out of order, a width is taken as
+ * unknown — a breakpoint can't sit narrower than the one before it.
+ */
+export function widthsFor(
+  names: string[],
+  known: Record<string, number> = {},
+): number[] {
+  const out: number[] = [];
+  names.forEach((name, i) => {
+    const previous = out[i - 1] ?? 0;
+    const given = known[name] ?? FALLBACK_WIDTHS[name.toLowerCase()];
+    out.push(
+      given !== undefined && given > previous
+        ? given
+        : previous
+          ? previous + 400
+          : 400,
+    );
+  });
+  return out;
+}
+
+/** A number as CSS writes it: no trailing zeros, at most `places` decimals. */
+export const trimNumber = (n: number, places = 4) =>
+  String(Number(n.toFixed(places)));
+
+/**
+ * A length fluid between two viewport widths, as CSS: `from` at `w0`, `to`
+ * at `w1`, straight between and held beyond — a clamp() over vw, or the
+ * length alone when it doesn't change. `length` writes a px value in the
+ * caller's unit, such as `(px) => `${px / 16}rem``.
+ */
+export function fluidClamp(
+  from: number,
+  to: number,
+  w0: number,
+  w1: number,
+  length: (px: number) => string,
+): string {
+  if (w1 === w0 || Math.abs(from - to) < 1e-9) return length(from);
+  const slope = (to - from) / (w1 - w0);
+  const intercept = from - slope * w0;
+  const vw = slope * 100;
+  const sign = vw < 0 ? "-" : "+";
+  return `clamp(${length(Math.min(from, to))}, ${length(intercept)} ${sign} ${trimNumber(Math.abs(vw))}vw, ${length(Math.max(from, to))})`;
+}

package/src/lib/colors.js

@@ -1,80 +0,0 @@
-/**
- * Color utilities for Figma plugins
- */
-
-/**
- * Convert RGB color (0-1 range) to HEX string
- * @param {{r: number, g: number, b: number}} color - RGB color with values 0-1
- * @returns {string} HEX color string (e.g., "#FF0000")
- */
-export function rgbToHex({ r, g, b }) {
-  const toHex = (value) => {
-    const hex = Math.round(value * 255)
-      .toString(16)
-      .padStart(2, "0");
-    return hex;
-  };
-  return `#${toHex(r)}${toHex(g)}${toHex(b)}`.toUpperCase();
-}
-
-/**
- * Convert HEX string to RGB color (0-1 range)
- * @param {string} hex - HEX color string (e.g., "#FF0000" or "FF0000")
- * @returns {{r: number, g: number, b: number} | null} RGB color with values 0-1, or null if invalid
- */
-export function hexToRgb(hex) {
-  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 };
-}
-
-/**
- * Get relative luminance of a color (for contrast calculations)
- * @param {{r: number, g: number, b: number}} color - RGB color with values 0-1
- * @returns {number} Relative luminance (0-1)
- */
-export function getLuminance({ r, g, b }) {
-  const adjust = (c) =>
-    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);
-}
-
-/**
- * Calculate contrast ratio between two colors (WCAG formula)
- * @param {{r: number, g: number, b: number}} color1 - First RGB color (0-1 range)
- * @param {{r: number, g: number, b: number}} color2 - Second RGB color (0-1 range)
- * @returns {number} Contrast ratio (1-21)
- */
-export function getContrastRatio(color1, color2) {
-  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);
-}
-
-/**
- * Check if contrast ratio meets WCAG level
- * @param {number} ratio - Contrast ratio
- * @param {"AA" | "AAA" | "AA-large" | "AAA-large"} level - WCAG level to check
- * @returns {boolean} Whether the ratio meets the level
- */
-export function meetsContrastLevel(ratio, level) {
-  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;
-  }
-}