figma-plugin-utilities 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-10
+
+### Added
+- `figma-plugin-utilities/vite` — `figmaPluginConfig(import.meta.url)`, a plugin's whole Vite config: each thread built on its own (`vite build && vite build --mode code`), so both may import the same module, the UI's CSS and JS inlined into `dist/index.html`, `src/manifest.json` copied, at `es2017`. `moduleScript` inlines the UI as a module script. `ui3InlineSvg` and `inlineFigmaHtml` are exported too. `vite` and `@sveltejs/vite-plugin-svelte` are optional peer dependencies
+- **EmptyState** — `iconSize`, the icon's size in px (24 by default), for an icon given as SVG markup
+- **FieldGroup** — `hint`, a line of secondary text under the control: what to enter, or what the choice does. Empty shows none, so a conditional hint is a string; the `hint` slot takes markup and always shows. Like the label, it can't be selected. The hint and the control's error take the label's size: body-medium, or body-small in a small group. The Figma component has the hint too, which Code Connect and the mockup builder read
+
+### Changed
+- **figma-ui3-kit-svelte** peer is `^0.8.0`, whose Input, Textarea, Dropdown and Dropzone size their error by the `--field-error-*` properties FieldGroup sets
+- `resizeToFit` — measures only the `container` you pass, and without one or a `height` warns and leaves the window as it is. It measured `document.body` by default, which fills the window, so the window could grow but never shrink
+
+### Fixed
+- `sendToUI`, `sendToPlugin` — a `type` field in the data no longer replaces the message's type
+- `formatErrorMessage` — the network, CORS and JSON messages follow the copy guidelines: no "Please" or "Network error:" prefix
+- **FieldGroup** — `labelFor` ties the label to its control, so clicking the label focuses an `Input` or `Textarea`. It was passed to Label as `for`, which Label doesn't take, so no label was tied to anything
+- **EmptyState** — `icon`, `action` and `actions` have types, so a plugin's `svelte-check` with `checkJs` passes
+- `autoResize` — the options default to `{ container: null }`, which matches their type; without a container it still warns and does nothing
+
+## [0.5.1] - 2026-10-07
+
+### Changed
+- **figma-ui3-kit-svelte** is a peer dependency, `^0.7.0`: install it beside the utilities. 0.7.0 is what `confirmDiscardChanges` needs for Modal's `beforeClose`, and **ConfirmModal** over another modal for Escape to close only the top one
+
 ## [0.5.0] - 2026-10-07
 
 ### Added
@@ -56,7 +79,7 @@
 - The dev-mode `console.warn` **FieldGroup** logged when `label` was set without `labelFor` — a `Dropdown` is a button and cannot be a `<label for>` target, so it fired on correct code. Dropped in the a11y pass, recorded late
 
 ### Fixed
-- **StatusBar** — the default `info` type sets `color: var(--figma-color-text)`. The `error`, `success` and `warning` types each set a foreground; the default one relied on inheritance, and nothing up the tree sets `color`, so the message rendered in the UA's black on the dark theme's grey bar
+- **StatusBar** — the default `info` type sets `color: var(--figma-color-text)`. The `error`, `success` and `warning` types each set a foreground; the default one relied on inheritance, and nothing up the tree sets `color`, so the message rendered in the UA's black on the dark theme's gray bar
 - **EmptyState** — the actions are a keyed `{#each}`, so swapping one action for another reuses the right button rather than repainting the row
 - **docs** — `figma-frame-builders` is documented, `sanitizeInput` no longer claims to escape HTML (it stringifies, truncates, strips control characters and trims), and `formatErrorMessage`, `handleAsyncError`, `withErrorHandling` and `logError` are documented with their real signatures. `withErrorHandling(fn, operation)` calls `fn()` with no arguments and returns its result; it was documented as returning a wrapped function
 

package/README.md

@@ -5,9 +5,11 @@ Shared Svelte components and utilities for Figma plugins.
 ## Installation
 
 ```bash
-npm install figma-plugin-utilities
+npm install figma-plugin-utilities figma-ui3-kit-svelte
 ```
 
+The components are built from `figma-ui3-kit-svelte`, a peer dependency: install it beside the utilities.
+
 ## Usage
 
 ### Import Everything
@@ -78,10 +80,10 @@ import { sendToPlugin, createMessageHandler } from "figma-plugin-utilities/lib";
 | `Header` | Header bar with `left`, `center`, `right` slots and optional title |
 | `Footer` | Footer with `right`, `split`, and `full` layout variants |
 | `StatusBar` | Toast notifications with auto-dismiss (info/success/error/warning) |
-| `EmptyState` | Empty/error states with optional icon and action buttons; `size`, `centered`, and `role="alert"` for failures |
+| `EmptyState` | Empty/error states with optional icon and action buttons; `size`, `iconSize`, `centered`, and `role="alert"` for failures |
 | `ListItem` | Selectable list items with metadata and `badge` slots, an action menu (`menuOpen`, `menuToggle`, `menuClose`) |
-| `LoadingState` | Centred message as `role="status"` (text only, no spinner) |
-| `FieldGroup` | Label + input wrapper; `labelFor` binds the label to a text control |
+| `LoadingState` | Centered message as `role="status"` (text only, no spinner) |
+| `FieldGroup` | Label + input wrapper; `labelFor` binds the label to a text control, `hint` adds a line under it |
 | `CheckboxCard` | Large checkbox with card styling and better touch targets; `change` event |
 | `Section` | Titled group of fields as in Figma's panels: a `Header` with the title and an `actions` slot, content padded by the section itself |
 | `DataTable` | Named rows with a cell per column (a set at each breakpoint, a style before and after): columns with their own width and alignment, a read-only mode with table roles, row selection with an `editor` slot, notes as badges, with tooltips, and a `+N` count past two, an `action` slot, values as badges or variable chips, removed rows and a marked column |
@@ -377,8 +379,8 @@ const parsed = parseJsonSafe(jsonString);
 Utilities for dynamically resizing the plugin window to fit its content.
 
 ```javascript
-// One-time resize to fit content
-resizeToFit({ width: 300, minHeight: 100, maxHeight: 600 });
+// One-time resize to fit content: measure a naturally-flowing wrapper, not document.body
+resizeToFit({ container: myContainerEl, width: 300, minHeight: 100, maxHeight: 600 });
 
 // Watch for content changes and auto-resize
 const cleanup = autoResize({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-plugin-utilities",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Shared Svelte components and utilities for Figma plugins",
   "type": "module",
   "svelte": "./src/index.js",
@@ -58,6 +58,11 @@
       "types": "./src/lib/confirm.ts",
       "import": "./src/lib/confirm.ts",
       "default": "./src/lib/confirm.ts"
+    },
+    "./vite": {
+      "types": "./src/vite.d.ts",
+      "import": "./src/vite.js",
+      "default": "./src/vite.js"
     }
   },
   "files": [
@@ -84,6 +89,19 @@
   ],
   "author": "Marius Roosendaal",
   "license": "MIT",
+  "peerDependencies": {
+    "figma-ui3-kit-svelte": "^0.8.0",
+    "@sveltejs/vite-plugin-svelte": "^3.0.2",
+    "vite": "^5.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@sveltejs/vite-plugin-svelte": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@figma/plugin-typings": "^1.138.0",
@@ -91,7 +109,7 @@
     "@types/node": "^22.13.4",
     "eslint": "^9.39.2",
     "eslint-plugin-svelte": "^3.23.0",
-    "figma-ui3-kit-svelte": "^0.6.0",
+    "figma-ui3-kit-svelte": "^0.8.0",
     "globals": "^17.12.0",
     "prettier": "^3.9.8",
     "prettier-plugin-svelte": "^3.4.0",

package/src/components/EmptyState.svelte

@@ -7,7 +7,7 @@
    * @example
    * <EmptyState
    *   message="No items found"
-   *   icon="search"
+   *   icon={IconSearch}
    *   actions={[{ label: "Add Item", handler: handleAdd }]}
    * />
    */
@@ -15,13 +15,31 @@
   /** Message to display */
   export let message = "";
 
-  /** Optional icon (string name or component) */
+  /**
+   * Optional icon: SVG markup, such as an icon from figma-ui3-kit-svelte/icons, or a component
+   * @type {string | import("svelte").ComponentType | null}
+   */
   export let icon = null;
 
-  /** Single action for backward compatibility { label, handler } */
+  /** Icon size in px, for an icon given as SVG markup; the svg is scaled to it */
+  export let iconSize = 24;
+
+  /**
+   * @typedef {object} EmptyStateAction
+   * @property {string} label
+   * @property {() => void} handler
+   */
+
+  /**
+   * Single action for backward compatibility { label, handler }
+   * @type {EmptyStateAction | null}
+   */
   export let action = null;
 
-  /** Multiple actions [{ label, handler }] */
+  /**
+   * Multiple actions [{ label, handler }]
+   * @type {EmptyStateAction[] | null}
+   */
   export let actions = null;
 
   /** Size variant: 'small', 'medium', 'large' */
@@ -49,7 +67,7 @@
   {#if icon}
     <div class="empty-state__icon" aria-hidden="true">
       {#if typeof icon === "string"}
-        <Icon iconName={icon} />
+        <Icon iconName={icon} size={iconSize} />
       {:else}
         <svelte:component this={icon} />
       {/if}
@@ -111,6 +129,12 @@
     line-height: var(--body-large-line-height);
   }
 
+  /* Icon sizes its box, but the svg keeps the 24px it's drawn at. */
+  .empty-state__icon :global(.icon-component svg) {
+    width: 100%;
+    height: 100%;
+  }
+
   .empty-state__actions {
     display: flex;
     flex-direction: row;

package/src/components/FieldGroup.svelte

@@ -1,5 +1,5 @@
 <script>
-  import { Label } from "figma-ui3-kit-svelte";
+  import { Label, Text } from "figma-ui3-kit-svelte";
 
   /** Label text (optional) */
   export let label = "";
@@ -9,23 +9,58 @@
 
   /** Size of the label (optional) */
   export let size = undefined;
+
+  /**
+   * A line under the control: what to enter, or what the choice does
+   * (optional). Empty shows none, so a conditional hint is a string; the
+   * `hint` slot takes markup and always shows. It takes the label's size, as
+   * the control's error does: body-medium, or body-small in a small group.
+   */
+  export let hint = "";
 </script>
 
 <div class="field-group" class:small={size === "small"}>
   {#if label}
-    <Label for={labelFor} {size}>{label}</Label>
+    <Label htmlFor={labelFor} {size}>{label}</Label>
   {/if}
   <slot />
+  {#if $$slots.hint || hint}
+    <Text
+      class="field-group__hint"
+      variant={size === "small" ? "body-small" : "body-medium"}
+      color="--figma-color-text-secondary"
+      block
+    >
+      <slot name="hint">{hint}</slot>
+    </Text>
+  {/if}
 </div>
 
 <style>
+  /* The control's error takes the label's size, as the hint does. Read by
+     the kit's Input, Textarea, Dropdown and Dropzone errors, and set on every
+     group so a default group inside a small one is medium again. */
   .field-group {
     display: flex;
     flex-direction: column;
     gap: var(--size-xxsmall);
+    --field-error-font-size: var(--body-medium-font-size);
+    --field-error-font-weight: var(--body-medium-font-weight);
+    --field-error-letter-spacing: var(--body-medium-letter-spacing);
+    --field-error-line-height: var(--body-medium-line-height);
   }
 
   .field-group.small {
     gap: var(--size-xxxsmall);
+    --field-error-font-size: var(--body-small-font-size);
+    --field-error-font-weight: var(--body-small-font-weight);
+    --field-error-letter-spacing: var(--body-small-letter-spacing);
+    --field-error-line-height: var(--body-small-line-height);
+  }
+
+  /* Like the label, the hint is interface text, not content to copy */
+  .field-group :global(.field-group__hint) {
+    cursor: default;
+    user-select: none;
   }
 </style>

package/src/lib/errorHandling.js

@@ -44,12 +44,13 @@ export function formatErrorMessage(error, context) {
   // 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.";
+      "Couldn't connect to the server. 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.";
+      "The resource host doesn't allow plugin access. Try resources from allowed domains.";
   } else if (message.includes("JSON")) {
-    userMessage = "Invalid JSON format. Please check your data and try again.";
+    userMessage =
+      "Couldn't read the data as JSON. Check its format and try again.";
   } else if (message.includes("not found")) {
     userMessage = message
       .replace(/not found/gi, "not found")

package/src/lib/figma-helpers.ts

@@ -12,7 +12,7 @@ export function sendToUI<T extends Record<string, unknown>>(
   data?: T,
 ): void {
   if (data) {
-    figma.ui.postMessage({ type, ...data });
+    figma.ui.postMessage({ ...data, type });
   } else {
     figma.ui.postMessage({ type });
   }

package/src/lib/messages.js

@@ -8,7 +8,7 @@
  * @param {object} data - Additional data to send
  */
 export function sendToPlugin(type, data = {}) {
-  parent.postMessage({ pluginMessage: { type, ...data } }, "*");
+  parent.postMessage({ pluginMessage: { ...data, type } }, "*");
 }
 
 /**

package/src/lib/resize.js

@@ -3,8 +3,8 @@
  *
  * Usage in UI:
  *   import { resizeToFit, autoResize } from "figma-plugin-utilities";
- *   resizeToFit(); // One-time resize
- *   autoResize();  // Watch for changes and auto-resize
+ *   resizeToFit({ container }); // One-time resize to a content wrapper
+ *   autoResize({ container });  // Watch for changes and auto-resize
  *
  * Usage in code.ts:
  *   import { handleResize } from "figma-plugin-utilities/lib/figma-helpers";
@@ -46,7 +46,10 @@ export function getContentHeight(container) {
  * @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
+ * @param {HTMLElement} [options.container] - Container element to measure,
+ *   required without `height`. Not `document.body`: the kit sets
+ *   `html, body, #app { height: 100% }`, so the body measures the window,
+ *   which then can grow but never shrink.
  */
 export function resizeToFit(options = {}) {
   const {
@@ -55,12 +58,16 @@ export function resizeToFit(options = {}) {
     minHeight = 100,
     maxHeight = 800,
     padding = 0,
-    container = document.body,
+    container,
   } = options;
 
   let finalHeight = height;
 
   if (finalHeight === undefined) {
+    if (!container) {
+      console.warn("resizeToFit: pass a height, or a container to measure");
+      return;
+    }
     finalHeight = getContentHeight(container) + padding;
   }
 
@@ -78,7 +85,7 @@ export function resizeToFit(options = {}) {
  * 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 {HTMLElement | null} 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
@@ -87,7 +94,7 @@ export function resizeToFit(options = {}) {
  * @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 = {}) {
+export function autoResize(options = { container: null }) {
   const {
     container,
     width = defaultWidth,

package/src/vite.d.ts

@@ -0,0 +1,13 @@
+import type { Plugin, UserConfigFnObject } from "vite";
+
+export function ui3InlineSvg(): Plugin;
+
+export function inlineFigmaHtml(options: {
+  root: string;
+  moduleScript?: boolean;
+}): Plugin;
+
+export function figmaPluginConfig(
+  configUrl: string,
+  options?: { moduleScript?: boolean },
+): UserConfigFnObject;

package/src/vite.js

@@ -0,0 +1,165 @@
+// Vite config for a Figma plugin: `src/index.html` and `src/code.ts` in, and
+// `dist/index.html`, `dist/code.js` and `dist/manifest.json` out.
+//
+// Two builds, one per thread: the UI (`vite build`) and the sandbox
+// (`vite build --mode code`). Built together, a module both import becomes a
+// shared chunk, and code.js starts with an `import` Figma's sandbox can't load
+// ("expecting '('"). Apart, each is one self-contained file, so the threads can
+// share code, such as lib/scale.
+import { dirname, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+
+// Figma's JS sandbox doesn't support ES2020+ (no ?. or ??)
+const TARGET = "es2017";
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Bundles figma-ui3-kit-svelte's SVG imports as strings, for its icons.
+ * @returns {import("vite").Plugin}
+ */
+export function ui3InlineSvg() {
+  return {
+    name: "ui3-inline-svg",
+    enforce: "pre",
+    load(id) {
+      if (!id.includes("figma-ui3-kit-svelte")) return;
+      const filePath = id.split("?")[0];
+      if (!filePath.endsWith(".svg")) return;
+      const svg = readFileSync(filePath, "utf-8");
+      return `export default ${JSON.stringify(svg)};`;
+    },
+  };
+}
+
+/**
+ * Inlines the UI build's CSS and JS into one `index.html`, as Figma needs, and
+ * copies `src/manifest.json` to the output.
+ *
+ * Replacements are functions, so a `$&` in minified code isn't read as a
+ * pattern.
+ * @param {{ root: string, moduleScript?: boolean }} options
+ * @returns {import("vite").Plugin}
+ */
+export function inlineFigmaHtml({ root, moduleScript = false }) {
+  const scriptTag = moduleScript ? '<script type="module">' : "<script>";
+  return {
+    name: "inline-figma-html",
+    apply: "build",
+    enforce: "post",
+    generateBundle(_options, bundle) {
+      const htmlKey =
+        Object.keys(bundle).find((key) => key.endsWith("index.html")) ?? "";
+      const htmlAsset = htmlKey ? bundle[htmlKey] : undefined;
+      if (!htmlAsset || htmlAsset.type !== "asset") return;
+
+      let html = String(htmlAsset.source);
+      html = html.replace(/<link\s+[^>]*rel=["']modulepreload["'][^>]*>/gi, "");
+
+      for (const [fileName, asset] of Object.entries(bundle)) {
+        if (asset.type !== "asset" || !fileName.endsWith(".css")) continue;
+        const css = String(asset.source ?? "");
+        const hrefPattern = new RegExp(
+          `<link[^>]+rel=["']stylesheet["'][^>]+href=["'](?:\\./|/|\\.\\./)?${escapeRegExp(
+            fileName,
+          )}["'][^>]*>`,
+          "i",
+        );
+        if (hrefPattern.test(html)) {
+          html = html.replace(hrefPattern, () => `<style>${css}</style>`);
+          delete bundle[fileName];
+        }
+      }
+
+      for (const [fileName, chunk] of Object.entries(bundle)) {
+        if (chunk.type !== "chunk") continue;
+        const scriptPattern = new RegExp(
+          `<script[^>]+src=["'](?:\\./|/|\\.\\./)?${escapeRegExp(
+            fileName,
+          )}["'][^>]*></script>`,
+          "i",
+        );
+        if (scriptPattern.test(html)) {
+          html = html.replace(
+            scriptPattern,
+            () => `${scriptTag}${chunk.code}</script>`,
+          );
+          delete bundle[fileName];
+        }
+      }
+
+      htmlAsset.source = html;
+      if (htmlKey !== "index.html") {
+        delete bundle[htmlKey];
+        htmlAsset.fileName = "index.html";
+        bundle["index.html"] = htmlAsset;
+      }
+
+      this.emitFile({
+        type: "asset",
+        fileName: "manifest.json",
+        source: readFileSync(resolve(root, "src/manifest.json"), "utf-8"),
+      });
+    },
+  };
+}
+
+/**
+ * The plugin's Vite config, for `vite.config.ts`:
+ *
+ *   export default figmaPluginConfig(import.meta.url);
+ *
+ * Build with `vite build && vite build --mode code`.
+ *
+ * `moduleScript` inlines the UI as `<script type="module">`, which runs once
+ * the page is parsed. Without it the script is classic and runs in `<head>`,
+ * so `main.js` waits for DOMContentLoaded before it mounts.
+ * @param {string} configUrl `import.meta.url` of the plugin's vite.config.ts
+ * @param {{ moduleScript?: boolean }} [options]
+ * @returns {import("vite").UserConfigFnObject}
+ */
+export function figmaPluginConfig(configUrl, { moduleScript = false } = {}) {
+  const root = dirname(fileURLToPath(configUrl));
+  return ({ mode }) =>
+    mode === "code"
+      ? {
+          base: "./",
+          build: {
+            outDir: "dist",
+            emptyOutDir: false, // The UI build's index.html and manifest.json stay
+            target: TARGET,
+            rollupOptions: {
+              input: resolve(root, "src/code.ts"),
+              output: {
+                entryFileNames: "code.js",
+                inlineDynamicImports: true,
+              },
+            },
+          },
+        }
+      : {
+          base: "./",
+          plugins: [
+            ui3InlineSvg(),
+            svelte(),
+            inlineFigmaHtml({ root, moduleScript }),
+          ],
+          build: {
+            outDir: "dist",
+            emptyOutDir: false, // The sandbox build's code.js stays
+            target: TARGET,
+            rollupOptions: {
+              input: resolve(root, "src/index.html"),
+              output: {
+                entryFileNames: "[name].js",
+                chunkFileNames: "[name]-[hash].js",
+                assetFileNames: "[name]-[hash][extname]",
+              },
+            },
+          },
+        };
+}