figma-plugin-utilities 0.1.0

package/src/components/ListItem.svelte

@@ -0,0 +1,172 @@
+<script>
+  import { createEventDispatcher } from "svelte";
+  import { IconButton, IconMore, Menu } from "figma-ui3-kit-svelte";
+
+  /**
+   * List item with optional action menu
+   *
+   * @example
+   * <ListItem
+   *   id="item-1"
+   *   title="My Item"
+   *   active={selectedId === 'item-1'}
+   *   menuItems={[
+   *     { label: 'Edit', value: 'edit' },
+   *     { label: 'Delete', value: 'delete' }
+   *   ]}
+   *   on:click={handleSelect}
+   *   on:menuSelect={handleMenuAction}
+   * >
+   *   <span>Additional info</span>
+   * </ListItem>
+   */
+
+  const dispatch = createEventDispatcher();
+
+  /** Unique identifier */
+  export let id;
+
+  /** Display title */
+  export let title;
+
+  /** Whether item is selected/active */
+  export let active = false;
+
+  /** Menu items [{ label, value }] */
+  export let menuItems = [];
+
+  /** Whether menu is open (bindable) */
+  export let menuOpen = false;
+
+  /** Reference to menu button element */
+  export let menuButtonElement = null;
+
+  /** Whether to show badge slot */
+  export let hasBadge = false;
+
+  function handleClick() {
+    dispatch("click", { id });
+  }
+
+  function handleMenuToggle(e) {
+    e.stopPropagation();
+    menuOpen = !menuOpen;
+    dispatch("menuToggle", { id, open: menuOpen });
+  }
+
+  function handleMenuSelect(e) {
+    dispatch("menuSelect", { id, action: e.detail.value });
+    menuOpen = false;
+  }
+
+  function handleMenuClose() {
+    menuOpen = false;
+    dispatch("menuClose", { id });
+  }
+</script>
+
+<div class="list-item-wrapper">
+  <div
+    class="list-item"
+    class:active
+    on:click={handleClick}
+    on:keydown={(e) => e.key === "Enter" && handleClick()}
+    role="button"
+    tabindex="0"
+  >
+    <div class="list-item__content">
+      <div class="list-item__title">{title}</div>
+      {#if $$slots.default}
+        <div class="list-item__meta">
+          <slot />
+        </div>
+      {/if}
+      {#if hasBadge && $$slots.badge}
+        <div class="list-item__badge">
+          <slot name="badge" />
+        </div>
+      {/if}
+    </div>
+  </div>
+
+  {#if menuItems.length > 0}
+    <IconButton
+      iconName={IconMore}
+      bind:element={menuButtonElement}
+      on:click={handleMenuToggle}
+    />
+    <Menu
+      bind:isOpen={menuOpen}
+      {menuItems}
+      anchorElement={menuButtonElement}
+      on:select={handleMenuSelect}
+      on:close={handleMenuClose}
+    />
+  {/if}
+</div>
+
+<style>
+  .list-item-wrapper {
+    display: flex;
+    align-items: center;
+    gap: var(--size-xxxsmall);
+    padding: var(--size-xxxsmall) 0;
+  }
+
+  .list-item {
+    flex: 1;
+    display: flex;
+    align-items: center;
+    padding: var(--size-xxsmall);
+    background: var(--figma-color-bg-secondary);
+    border: 1px solid transparent;
+    border-radius: var(--border-radius-medium);
+    cursor: pointer;
+    transition: border-color 0.15s ease;
+    min-width: 0;
+  }
+
+  .list-item:hover {
+    border-color: var(--figma-color-border-selected);
+  }
+
+  .list-item.active {
+    border-color: var(--figma-color-border-brand-strong);
+    background: var(--figma-color-bg-brand-tertiary);
+  }
+
+  .list-item__content {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    gap: var(--size-xxxsmall);
+    min-width: 0;
+  }
+
+  .list-item__title {
+    font-size: var(--body-medium-font-size);
+    font-weight: var(--body-medium-font-weight);
+    letter-spacing: var(--body-medium-letter-spacing);
+    line-height: var(--body-medium-line-height);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .list-item__meta {
+    display: flex;
+    align-items: center;
+    gap: var(--size-xxxsmall);
+    font-size: var(--body-medium-font-size);
+    font-weight: var(--body-medium-font-weight);
+    letter-spacing: var(--body-medium-letter-spacing);
+    line-height: var(--body-medium-line-height);
+    color: var(--figma-color-text-secondary);
+  }
+
+  .list-item__badge {
+    display: block;
+    min-width: 0;
+    overflow: hidden;
+  }
+</style>

package/src/components/LoadingState.svelte

@@ -0,0 +1,32 @@
+<script>
+  import { Text } from "figma-ui3-kit-svelte";
+
+  /**
+   * Loading state indicator
+   * Displays a centered message while content is loading
+   *
+   * @example
+   * {#if isLoading}
+   *   <LoadingState message="Loading collections..." />
+   * {:else}
+   *   <MainContent />
+   * {/if}
+   */
+
+  /** Message to display */
+  export let message = "Loading...";
+</script>
+
+<div class="loading-state">
+  <Text variant="body-medium" color="--figma-color-text-secondary">{message}</Text>
+</div>
+
+<style>
+  .loading-state {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    height: 100%;
+    padding: var(--size-medium);
+  }
+</style>

package/src/components/PluginLayout.svelte

@@ -0,0 +1,43 @@
+<script>
+  /**
+   * Standard plugin layout wrapper
+   * Provides consistent structure with main content area and optional footer
+   *
+   * @example
+   * <PluginLayout>
+   *   <p>Main content here</p>
+   *   <svelte:fragment slot="footer">
+   *     <Button variant="primary">Create item</Button>
+   *   </svelte:fragment>
+   * </PluginLayout>
+   */
+
+  /** Additional CSS classes for the wrapper */
+  export let className = "";
+</script>
+
+<div class="plugin-wrapper {className}">
+  <main class="plugin-main">
+    <slot />
+  </main>
+</div>
+
+<style>
+  .plugin-wrapper {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    color: var(--figma-color-text);
+    font-family: var(--figma-font-stack);
+    overflow: hidden;
+  }
+
+  .plugin-main {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    gap: var(--size-xsmall);
+    overflow-y: auto;
+    padding: var(--size-xsmall);
+  }
+</style>

package/src/components/StatusBar.svelte

@@ -0,0 +1,106 @@
+<script>
+  import { onDestroy, createEventDispatcher } from "svelte";
+  import { IconButton, IconClose } from "figma-ui3-kit-svelte";
+
+  // Status bar for notifications with auto-dismiss
+  // Supports types: 'info', 'success', 'error', 'warning'
+  // Auto-dismisses after 4s for 'info' and 'success' types
+
+  const dispatch = createEventDispatcher();
+
+  /** Message to display */
+  export let message = "";
+
+  /** Status type: 'info', 'success', 'error', 'warning' */
+  export let type = "info";
+
+  let visible = false;
+  let timeoutId;
+
+  $: shouldAutoDismiss = type === "success" || type === "info";
+
+  // Compute icon color based on type
+  $: computedIconColor =
+    type === "error"
+      ? "--figma-color-icon-ondanger"
+      : type === "success"
+        ? "--figma-color-icon-onsuccess"
+        : type === "warning"
+          ? "--figma-color-icon-onwarning"
+          : "--figma-color-icon";
+
+  // Show status when message changes
+  $: if (message) {
+    visible = true;
+    if (shouldAutoDismiss) {
+      clearTimeout(timeoutId);
+      timeoutId = setTimeout(() => handleClose(), 4000);
+    }
+  } else {
+    visible = false;
+  }
+
+  function handleClose() {
+    visible = false;
+    clearTimeout(timeoutId);
+    dispatch("close");
+  }
+
+  onDestroy(() => {
+    clearTimeout(timeoutId);
+  });
+</script>
+
+{#if visible && message}
+  <div
+    class="status-bar"
+    class:status-bar--error={type === "error"}
+    class:status-bar--success={type === "success"}
+    class:status-bar--warning={type === "warning"}
+  >
+    <span>{message}</span>
+    <IconButton
+      iconName={IconClose}
+      on:click={handleClose}
+      iconColor={computedIconColor}
+    />
+  </div>
+{/if}
+
+<style>
+  .status-bar {
+    position: relative;
+    height: var(--size-large);
+    padding: 0 var(--size-xxsmall) 0 var(--size-xsmall);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    background: var(--figma-color-bg-secondary);
+    font-size: var(--body-medium-font-size);
+    font-weight: var(--body-medium-font-weight);
+    letter-spacing: var(--body-medium-letter-spacing);
+    line-height: var(--body-medium-line-height);
+    overflow: hidden;
+  }
+
+  .status-bar > span {
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  .status-bar--error {
+    background: var(--figma-color-bg-danger);
+    color: var(--figma-color-text-ondanger);
+  }
+
+  .status-bar--success {
+    background: var(--figma-color-bg-success);
+    color: var(--figma-color-text-onsuccess);
+  }
+
+  .status-bar--warning {
+    background: var(--figma-color-bg-warning);
+    color: var(--figma-color-text-onwarning);
+  }
+</style>

package/src/components/index.js

@@ -0,0 +1,9 @@
+// Svelte components
+export { default as EmptyState } from "./EmptyState.svelte";
+export { default as FieldGroup } from "./FieldGroup.svelte";
+export { default as Footer } from "./Footer.svelte";
+export { default as ListItem } from "./ListItem.svelte";
+export { default as LoadingState } from "./LoadingState.svelte";
+export { default as PluginLayout } from "./PluginLayout.svelte";
+export { default as StatusBar } from "./StatusBar.svelte";
+export { default as Header } from "./Header.svelte";

package/src/index.js

@@ -0,0 +1,45 @@
+// Re-export all components
+export {
+  EmptyState,
+  FieldGroup,
+  Footer,
+  ListItem,
+  LoadingState,
+  PluginLayout,
+  StatusBar,
+  Header,
+} from "./components/index.js";
+
+// Re-export all utilities
+export {
+  // Messages
+  sendToPlugin,
+  createMessageHandler,
+  // Colors
+  rgbToHex,
+  hexToRgb,
+  getLuminance,
+  getContrastRatio,
+  meetsContrastLevel,
+  // Validation
+  validateUrl,
+  validateJsonString,
+  sanitizeInput,
+  sanitizeName,
+  validateEmail,
+  validateNumber,
+  isEmpty,
+  // Error handling
+  formatErrorMessage,
+  handleAsyncError,
+  createUserErrorMessage,
+  logError,
+  withErrorHandling,
+  safeAsync,
+  parseJsonSafe,
+  // Resize
+  setDefaultWidth,
+  getContentHeight,
+  resizeToFit,
+  autoResize,
+} from "./lib/index.js";

package/src/lib/colors.js

@@ -0,0 +1,77 @@
+/**
+ * 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"} 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 "AA":
+      return ratio >= 4.5;
+    case "AA-large":
+      return ratio >= 3;
+    default:
+      return false;
+  }
+}

package/src/lib/errorHandling.js

@@ -0,0 +1,186 @@
+/**
+ * Error handling utilities
+ *
+ * Provides standardized error handling functions for consistent
+ * error messages and error handling patterns across the plugin.
+ */
+
+/**
+ * @typedef {Object} FormattedError
+ * @property {string} message - Technical error message
+ * @property {string} userMessage - User-friendly error message
+ * @property {string} [technical] - Stack trace or detailed info
+ */
+
+/**
+ * Format an error into a user-friendly message
+ * @param {unknown} error - The error to format
+ * @param {string} [context] - Optional context to add to the message
+ * @returns {FormattedError}
+ */
+export function formatErrorMessage(error, context) {
+  let message = "An unexpected error occurred";
+  let technical = "";
+
+  if (error instanceof Error) {
+    message = error.message;
+    technical = error.stack || error.message;
+  } else if (typeof error === "string") {
+    message = error;
+    technical = error;
+  } else {
+    technical = String(error);
+    message = "An unknown error occurred";
+  }
+
+  // Add context if provided
+  if (context) {
+    message = `${context}: ${message}`;
+  }
+
+  // Create user-friendly version by removing technical details
+  let userMessage = message;
+
+  // Common error patterns to make more user-friendly
+  if (message.includes("Failed to fetch") || message.includes("NetworkError")) {
+    userMessage =
+      "Network error: Could not connect to the server. Please check your internet connection and try again.";
+  } else if (message.includes("CORS")) {
+    userMessage =
+      "CORS error: The resource host does not allow plugin access. Try resources from allowed domains.";
+  } else if (message.includes("JSON")) {
+    userMessage = "Invalid JSON format. Please check your data and try again.";
+  } else if (message.includes("not found")) {
+    userMessage = message
+      .replace(/not found/gi, "not found")
+      .replace(/^Error: /, "");
+  } else if (message.includes("Missing")) {
+    userMessage = message.replace(/^Error: /, "");
+  }
+
+  return {
+    message,
+    userMessage,
+    technical: technical || undefined,
+  };
+}
+
+/**
+ * Handle async errors with standardized formatting
+ * @param {unknown} error - The error to handle
+ * @param {string} operation - Description of the operation that failed
+ * @returns {FormattedError}
+ */
+export function handleAsyncError(error, operation) {
+  return formatErrorMessage(error, operation);
+}
+
+/**
+ * Create a user-friendly error message for UI display
+ * @param {unknown} error - The error to format
+ * @param {string} operation - Description of the operation that failed
+ * @returns {string}
+ */
+export function createUserErrorMessage(error, operation) {
+  return handleAsyncError(error, operation).userMessage;
+}
+
+/**
+ * Log error with context (for debugging)
+ * @param {unknown} error - The error to log
+ * @param {string} context - Context description
+ */
+export function logError(error, context) {
+  const formatted = formatErrorMessage(error, context);
+  console.error(`[${context}]`, formatted.message);
+  if (formatted.technical && formatted.technical !== formatted.message) {
+    console.error("Technical details:", formatted.technical);
+  }
+}
+
+/**
+ * Wrap an async function with error handling
+ * @template T
+ * @param {() => Promise<T>} fn - The async function to wrap
+ * @param {string} operation - Description of the operation
+ * @returns {Promise<T>}
+ */
+export async function withErrorHandling(fn, operation) {
+  try {
+    return await fn();
+  } catch (error) {
+    logError(error, operation);
+    throw error;
+  }
+}
+
+/**
+ * Wrap an async function and return a result object instead of throwing
+ * @template T
+ * @param {() => Promise<T>} fn - The async function to wrap
+ * @param {string} operation - Description of the operation
+ * @returns {Promise<{ ok: true, value: T } | { ok: false, error: FormattedError }>}
+ */
+export async function safeAsync(fn, operation) {
+  try {
+    const value = await fn();
+    return { ok: true, value };
+  } catch (error) {
+    const formatted = handleAsyncError(error, operation);
+    return { ok: false, error: formatted };
+  }
+}
+
+/**
+ * Parse JSON safely without throwing
+ * @param {string} jsonString - The JSON string to parse
+ * @returns {{ ok: true, value: any } | { ok: false, error: string }}
+ */
+export function parseJsonSafe(jsonString) {
+  try {
+    const value = JSON.parse(jsonString);
+    return { ok: true, value };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    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 });
+  }
+}