figma-plugin-utilities 0.1.0

package/src/lib/figma-helpers.ts

@@ -0,0 +1,129 @@
+/**
+ * Figma API helpers for plugin code (code.ts)
+ */
+
+/**
+ * Send a typed message to the UI
+ * @param type - Message type identifier
+ * @param data - Additional data to send
+ */
+export function sendToUI<T extends Record<string, unknown>>(
+  type: string,
+  data?: T
+): void {
+  if (data) {
+    figma.ui.postMessage({ type, ...data });
+  } else {
+    figma.ui.postMessage({ type });
+  }
+}
+
+/**
+ * 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);
+}
+
+/**
+ * Show an error notification to the user
+ * @param message - Error message to display
+ * @param timeout - How long to show the notification (ms)
+ */
+export function showError(message: string, timeout = 5000): void {
+  figma.notify(message, { error: true, timeout });
+}
+
+/**
+ * Show a success notification to the user
+ * @param message - Success message to display
+ * @param timeout - How long to show the notification (ms)
+ */
+export function showSuccess(message: string, timeout = 3000): void {
+  figma.notify(message, { timeout });
+}
+
+/**
+ * Get the current selection, optionally filtered by type
+ * @param nodeType - Optional node type to filter by
+ * @returns Array of selected nodes
+ */
+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[];
+}
+
+/**
+ * Focus the viewport on specific nodes
+ * @param nodes - Nodes to focus on
+ */
+export function focusNodes(nodes: readonly SceneNode[]): void {
+  if (nodes.length > 0) {
+    figma.viewport.scrollAndZoomIntoView(nodes);
+  }
+}
+
+/**
+ * Load a font before using it
+ * @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 });
+}
+
+/**
+ * Save data to client storage (persists across sessions)
+ * @param key - Storage key
+ * @param value - Value to store (must be JSON-serializable)
+ */
+export async function saveToStorage<T>(key: string, value: T): Promise<void> {
+  await figma.clientStorage.setAsync(key, value);
+}
+
+/**
+ * Load data from client storage
+ * @param key - Storage key
+ * @param defaultValue - Default value if key doesn't exist
+ * @returns Stored value or default
+ */
+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;
+  }
+}
+
+/**
+ * Handle resize message from UI
+ * Call this in your message handler when msg.type === "resize"
+ * @param msg - Message object with width and height
+ */
+export function handleResize(msg: { width: number; height: number }): void {
+  figma.ui.resize(msg.width, msg.height);
+}

package/src/lib/index.js

@@ -0,0 +1,47 @@
+// Message utilities
+export {
+  sendToPlugin,
+  createMessageHandler,
+} from "./messages.js";
+
+// Color utilities
+export {
+  rgbToHex,
+  hexToRgb,
+  getLuminance,
+  getContrastRatio,
+  meetsContrastLevel,
+} from "./colors.js";
+
+// Validation utilities
+export {
+  validateUrl,
+  validateJsonString,
+  sanitizeInput,
+  sanitizeName,
+  validateEmail,
+  validateNumber,
+  isEmpty,
+} from "./validation.js";
+
+// Error handling utilities
+export {
+  formatErrorMessage,
+  handleAsyncError,
+  createUserErrorMessage,
+  logError,
+  withErrorHandling,
+  safeAsync,
+  parseJsonSafe,
+  notifyError,
+  notifySuccess,
+  notifyWarning,
+} from "./errorHandling.js";
+
+// Resize utilities
+export {
+  setDefaultWidth,
+  getContentHeight,
+  resizeToFit,
+  autoResize,
+} from "./resize.js";

package/src/lib/messages.js

@@ -0,0 +1,36 @@
+/**
+ * Message utilities for Figma plugin UI communication
+ */
+
+/**
+ * Send a message to the plugin code
+ * @param {string} type - Message type identifier
+ * @param {object} data - Additional data to send
+ */
+export function sendToPlugin(type, data = {}) {
+  parent.postMessage({ pluginMessage: { type, ...data } }, "*");
+}
+
+/**
+ * Create a message handler with type-based routing
+ * @param {Record<string, (msg: any) => void>} handlers - Object mapping message types to handler functions
+ * @returns {(event: MessageEvent) => void} Event handler function
+ *
+ * @example
+ * window.onmessage = createMessageHandler({
+ *   populateOptions: (msg) => {
+ *     collections = msg.options;
+ *   },
+ *   generationComplete: () => {
+ *     isGenerating = false;
+ *   }
+ * });
+ */
+export function createMessageHandler(handlers) {
+  return (event) => {
+    const msg = event.data && event.data.pluginMessage;
+    if (!msg) return;
+    const handler = handlers[msg.type];
+    if (handler) handler(msg);
+  };
+}

package/src/lib/resize.js

@@ -0,0 +1,147 @@
+/**
+ * Auto-resize utilities for Figma plugin windows
+ *
+ * Usage in UI:
+ *   import { resizeToFit, autoResize } from "figma-plugin-utils";
+ *   resizeToFit(); // One-time resize
+ *   autoResize();  // Watch for changes and auto-resize
+ *
+ * Usage in code.ts:
+ *   import { handleResize } from "figma-plugin-utils/lib/figma-helpers";
+ *   // In your message handler:
+ *   if (msg.type === "resize") handleResize(msg);
+ */
+
+import { sendToPlugin } from "./messages.js";
+
+/** Default width for the plugin window */
+let defaultWidth = 300;
+
+/**
+ * Set the default width used for resize operations
+ * @param {number} width - The default width in pixels
+ */
+export function setDefaultWidth(width) {
+  defaultWidth = width;
+}
+
+/**
+ * Get the current content height of the plugin UI
+ * Uses scrollHeight which works when container doesn't have fixed height
+ * @param {HTMLElement} [container] - Container element to measure (should NOT have height: 100%)
+ * @returns {number} The content height in pixels
+ */
+export function getContentHeight(container) {
+  if (!container) {
+    return 0;
+  }
+  return container.scrollHeight;
+}
+
+/**
+ * Request the plugin to resize to fit content
+ * @param {object} [options] - Resize options
+ * @param {number} [options.width] - Width in pixels (uses default if not specified)
+ * @param {number} [options.height] - Height in pixels (auto-calculated if not specified)
+ * @param {number} [options.minHeight=100] - Minimum height in pixels
+ * @param {number} [options.maxHeight=800] - Maximum height in pixels
+ * @param {number} [options.padding=0] - Extra padding to add to calculated height
+ * @param {HTMLElement} [options.container] - Container element to measure
+ */
+export function resizeToFit(options = {}) {
+  const {
+    width = defaultWidth,
+    height,
+    minHeight = 100,
+    maxHeight = 800,
+    padding = 0,
+    container = document.body,
+  } = options;
+
+  let finalHeight = height;
+
+  if (finalHeight === undefined) {
+    finalHeight = getContentHeight(container) + padding;
+  }
+
+  // Clamp to min/max
+  finalHeight = Math.max(minHeight, Math.min(maxHeight, finalHeight));
+
+  sendToPlugin("resize", { width, height: finalHeight });
+}
+
+/**
+ * Set up automatic resizing when content changes
+ * Uses ResizeObserver to watch for size changes
+ * 
+ * IMPORTANT: The container element must NOT have height: 100% or fixed height.
+ * Use bind:this on a wrapper element that flows naturally with content.
+ * 
+ * @param {object} options - Auto-resize options
+ * @param {HTMLElement} options.container - Container element to observe (required, must not have fixed height)
+ * @param {number} [options.width] - Width in pixels (uses default if not specified)
+ * @param {number} [options.minHeight=100] - Minimum height in pixels
+ * @param {number} [options.maxHeight=800] - Maximum height in pixels
+ * @param {number} [options.padding=0] - Extra padding to add to calculated height
+ * @param {number} [options.debounce=50] - Debounce delay in milliseconds
+ * @param {number} [options.threshold=20] - Minimum height change to trigger resize (prevents position reset)
+ * @returns {function} Cleanup function to stop observing
+ */
+export function autoResize(options = {}) {
+  const {
+    container,
+    width = defaultWidth,
+    minHeight = 100,
+    maxHeight = 800,
+    padding = 0,
+    debounce = 50,
+    threshold = 20,
+  } = options;
+
+  if (!container) {
+    console.warn("autoResize: container is required");
+    return () => {};
+  }
+
+  let timeoutId = null;
+  let lastHeight = 0;
+
+  const doResize = () => {
+    const newHeight = getContentHeight(container) + padding;
+    const clampedHeight = Math.max(minHeight, Math.min(maxHeight, newHeight));
+
+    // Only resize if height changed by more than threshold (prevents position reset on small changes)
+    const heightDiff = Math.abs(clampedHeight - lastHeight);
+    if (lastHeight === 0 || heightDiff >= threshold) {
+      lastHeight = clampedHeight;
+      sendToPlugin("resize", { width, height: clampedHeight });
+    }
+  };
+
+  const debouncedResize = () => {
+    if (timeoutId) clearTimeout(timeoutId);
+    timeoutId = setTimeout(doResize, debounce);
+  };
+
+  // Initial resize
+  doResize();
+
+  // Watch for changes
+  const observer = new ResizeObserver(debouncedResize);
+  observer.observe(container);
+
+  // Also watch for DOM mutations (new elements added/removed)
+  const mutationObserver = new MutationObserver(debouncedResize);
+  mutationObserver.observe(container, {
+    childList: true,
+    subtree: true,
+    attributes: true,
+  });
+
+  // Return cleanup function
+  return () => {
+    if (timeoutId) clearTimeout(timeoutId);
+    observer.disconnect();
+    mutationObserver.disconnect();
+  };
+}

package/src/lib/validation.js

@@ -0,0 +1,234 @@
+/**
+ * Validation and sanitization utilities
+ *
+ * Provides input validation and sanitization for user-provided data
+ */
+
+/**
+ * Validate a URL string
+ * @param {string} url - The URL to validate
+ * @param {Object} [options] - Validation options
+ * @param {boolean} [options.required=true] - Whether URL is required
+ * @returns {{ valid: boolean, error?: string }}
+ */
+export function validateUrl(url, options = { required: true }) {
+  if (!url || typeof url !== "string" || !url.trim()) {
+    if (options.required) {
+      return { valid: false, error: "URL is required" };
+    }
+    return { valid: true };
+  }
+
+  const trimmed = url.trim();
+
+  try {
+    const urlObj = new URL(trimmed);
+
+    // Only allow http and https protocols
+    if (!["http:", "https:"].includes(urlObj.protocol)) {
+      return {
+        valid: false,
+        error: "URL must use http or https protocol",
+      };
+    }
+
+    // Validate hostname
+    if (!urlObj.hostname || urlObj.hostname.length === 0) {
+      return {
+        valid: false,
+        error: "Invalid URL: missing hostname",
+      };
+    }
+
+    // Check for suspicious patterns
+    const suspiciousPatterns = [
+      /javascript:/i,
+      /data:/i,
+      /vbscript:/i,
+      /file:/i,
+    ];
+
+    for (const pattern of suspiciousPatterns) {
+      if (pattern.test(trimmed)) {
+        return {
+          valid: false,
+          error: "URL contains invalid protocol",
+        };
+      }
+    }
+
+    return { valid: true };
+  } catch (err) {
+    return {
+      valid: false,
+      error: "Invalid URL format",
+    };
+  }
+}
+
+/**
+ * Validate a JSON string
+ * @param {string} jsonString - The JSON string to validate
+ * @param {Object} [options] - Validation options
+ * @param {number} [options.maxSizeKB] - Maximum size in KB
+ * @param {boolean} [options.requireObject] - Whether root must be an object
+ * @returns {{ valid: boolean, error?: string, parsed?: unknown }}
+ */
+export function validateJsonString(jsonString, options = {}) {
+  if (!jsonString || typeof jsonString !== "string") {
+    return {
+      valid: false,
+      error: "JSON string is required",
+    };
+  }
+
+  const trimmed = jsonString.trim();
+  if (!trimmed) {
+    return {
+      valid: false,
+      error: "JSON string is empty",
+    };
+  }
+
+  // Check size if specified
+  if (options.maxSizeKB) {
+    const sizeKB = Math.round(trimmed.length / 1024);
+    if (sizeKB > options.maxSizeKB) {
+      return {
+        valid: false,
+        error: `JSON is too large (${sizeKB} KB). Maximum size: ${options.maxSizeKB} KB`,
+      };
+    }
+  }
+
+  // Try to parse JSON
+  try {
+    const parsed = JSON.parse(trimmed);
+
+    // If requireObject is true, ensure it's an object
+    if (
+      options.requireObject &&
+      (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+    ) {
+      return {
+        valid: false,
+        error: "JSON must be an object",
+      };
+    }
+
+    return {
+      valid: true,
+      parsed,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Invalid JSON format";
+    return {
+      valid: false,
+      error: message,
+    };
+  }
+}
+
+/**
+ * Sanitize user input string
+ * @param {unknown} input - The input to sanitize
+ * @param {number} [maxLength] - Maximum length
+ * @returns {string}
+ */
+export function sanitizeInput(input, maxLength) {
+  if (input === null || input === undefined) {
+    return "";
+  }
+
+  let str = String(input);
+
+  // Apply length limit if provided
+  if (maxLength && str.length > maxLength) {
+    str = str.slice(0, maxLength);
+  }
+
+  // Remove null bytes and control characters (except newlines and tabs)
+  str = str.replace(/[\x00-\x08\x0B-\x0C\x0E-\x1F\x7F]/g, "");
+
+  // Trim whitespace
+  str = str.trim();
+
+  return str;
+}
+
+/**
+ * Sanitize a name/title for storage
+ * @param {unknown} name - The name to sanitize
+ * @param {number} [maxLength=200] - Maximum length
+ * @returns {string}
+ */
+export function sanitizeName(name, maxLength = 200) {
+  const sanitized = sanitizeInput(name, maxLength);
+
+  // Remove problematic characters but keep basic punctuation
+  // Allow: letters, numbers, spaces, hyphens, underscores, dots
+  return sanitized.replace(/[^a-zA-Z0-9\s\-_.]/g, "") || "Untitled";
+}
+
+/**
+ * Validate an email address
+ * @param {string} email - The email to validate
+ * @returns {{ valid: boolean, error?: string }}
+ */
+export function validateEmail(email) {
+  if (!email || typeof email !== "string" || !email.trim()) {
+    return { valid: false, error: "Email is required" };
+  }
+
+  // Basic email regex
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  if (!emailRegex.test(email.trim())) {
+    return { valid: false, error: "Invalid email format" };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Validate a number within range
+ * @param {unknown} value - The value to validate
+ * @param {Object} [options] - Validation options
+ * @param {number} [options.min] - Minimum value
+ * @param {number} [options.max] - Maximum value
+ * @param {boolean} [options.integer] - Must be an integer
+ * @returns {{ valid: boolean, error?: string, value?: number }}
+ */
+export function validateNumber(value, options = {}) {
+  const num = Number(value);
+
+  if (isNaN(num)) {
+    return { valid: false, error: "Must be a number" };
+  }
+
+  if (options.integer && !Number.isInteger(num)) {
+    return { valid: false, error: "Must be an integer" };
+  }
+
+  if (options.min !== undefined && num < options.min) {
+    return { valid: false, error: `Must be at least ${options.min}` };
+  }
+
+  if (options.max !== undefined && num > options.max) {
+    return { valid: false, error: `Must be at most ${options.max}` };
+  }
+
+  return { valid: true, value: num };
+}
+
+/**
+ * Check if a value is empty (null, undefined, empty string, empty array)
+ * @param {unknown} value - The value to check
+ * @returns {boolean}
+ */
+export function isEmpty(value) {
+  if (value === null || value === undefined) return true;
+  if (typeof value === "string" && value.trim() === "") return true;
+  if (Array.isArray(value) && value.length === 0) return true;
+  if (typeof value === "object" && Object.keys(value).length === 0) return true;
+  return false;
+}