figma-plugin-utilities 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -2,10 +2,50 @@
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-10-07
+
+### Changed
+- Built against **figma-ui3-kit-svelte** 0.7.0, which `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
+- **ConfirmModal** with `confirmAction`, from Data Mapper — a confirmation in a small modal in place of the browser's `confirm()`, resolving true or false, its buttons stacked at full width in a window too narrow for them side by side — and `confirmDiscardChanges`, the "Discard changes?" prompt before unsaved edits go, for Modal's `beforeClose`
+- **MappingChip** — one side of a source → target row as a filled 24px chip: a button with a lead icon or chit, a truncating `label`, an optional `preview` and `count`. `tone` is `default`, `secondary` or `component`; `selected` draws the selection border
+- **FieldGrid** — fields side by side in `columns` equal columns (2 by default) that shrink below their content
+- **SteppedField** — a field with − and + icon buttons after it, named by `downLabel` and `upLabel`, firing `step` with -1 or 1
+- **LadderBadges** — a scale's sizes as badges, outlined where used and `archived` where not, each with a tooltip
+- **RampCurve** — a ramp's quadratic Bézier at one breakpoint, the others faint behind it. At the smallest and largest breakpoint the ends and the bend are draggable or stepped with the arrow keys. Fires `change` and `select`
+- **CodeExportModal** — read-only code in a modal with a copy button that reads "Copied" for two seconds, and a `controls` slot for options above the code
+- **Section** — a titled group of fields as in Figma's panels, with icon buttons in an `actions` slot. It pads its own content and shrinks with its container
+- **DataTable** — named rows with a cell per column. Selectable rows open an `editor` slot; with `selectable={false}` it's a read-only table. Rows take badges with tooltips, and cells are badges, variable chips or text, colored as new, changed or danger
+- `lib/scale` — responsive scale math with no Figma API: the ramp's Bézier (`bezier`, `clampPosition`, `levelT`), `blendAt`, `valueAtWidth`, fallback breakpoint widths (`FALLBACK_WIDTHS`, `isBreakpointName`, `widthsFor`), `fluidClamp`, `trimNumber`, `lerp` and `roundHalfDown`
+- `lib/figma-variables` — `isVariableAlias`, `isColorValue`, `toRgba`, `getVariableLookup`, and `resolveVariableValue` and `resolveVariableValueAsync`, which follow aliases at a mode; the async one follows library variables too
+- **figma-helpers** — `fontsOf`, `loadFontOnce`, `loadNodeFonts` and `setText` write text in the layer's own fonts, loading each font once per run; `createSettingsStore` keeps settings in clientStorage, cleaned by one `sanitize` on load and on save
+- `isValidHex` — six HEX digits in either case, the "#" required unless `requireHash` is false
+- `plural` and `joinList` — "3 layers", "a, b and c"; from the root, or `lib/format` in code.ts
+- **figma-helpers** — `showNotice`, a regular notification for a run with nothing to do, where `showError` is for failures
+- `UNDO` — "Press Ctrl/Cmd+Z to undo.", the last sentence of a success notification for a change to the file
+
+### Changed
+- **ListItem** — an `actions` slot puts buttons inside the item, after its text and outside its clickable area, in the Figma component too (**Actions slot**)
+- **Header** — `level` sets the title's heading level (1 by default). The left padding is 8px when the left slot has content and 16px before a title alone, in the Figma component too
+- **Footer** — a kit `Text` at the edge of a split footer sits 16px in, where buttons sit 8px in
+- `rgbToHex` takes `lowercase`, `hash` and `alpha` options and clamps channels to 0–1
+- The color utilities are TypeScript, with their own `lib/colors` entry for code.ts
+- `loadFont` loads each font once per run
+- `showError` and `showSuccess` stay up long enough to read by default, about 60ms a character, and at least 5s and 3s
+- **figma-frame-builders** — `createTokenChip` pads its label 6px on each side, and `specTokens.accentColors.green` is #40C459, as in the Vitrine spec library
+
+### Removed
+- `getCollections`, `getVariables` and `getSelection` — call the Figma API directly
+- `saveToStorage` and `loadFromStorage` — use `createSettingsStore`
+- `notifyError`, `notifySuccess` and `notifyWarning`, which did nothing in the UI — use `showError` and `showSuccess` in code.ts
+
 ## [0.4.0] - 2026-09-21
 
 ### Added
-- `figma-frame-builders.ts` — new module with Figma frame and component builder utilities, imported from `figma-plugin-utilities/lib/figma-frame-builders` (its own export entry). They mirror the Vitrine spec library — colours, typography, spacing and layer names (`label` chip and text, a `tokens` row in token cells, `title` in both header variants):
+- `figma-frame-builders.ts` — new module with Figma frame and component builder utilities, imported from `figma-plugin-utilities/lib/figma-frame-builders` (its own export entry). They mirror the Vitrine spec library — colors, typography, spacing and layer names (`label` chip and text, a `tokens` row in token cells, `title` in both header variants):
   - `createAutoLayoutFrame` — creates a `FrameNode` with auto-layout configured
   - `createAutoLayoutComponent` — creates a `ComponentNode` with auto-layout configured
   - `createText` — creates a styled `TextNode`

package/README.md

@@ -24,6 +24,14 @@ import {
   LoadingState,
   FieldGroup,
   CheckboxCard,
+  Section,
+  DataTable,
+  FieldGrid,
+  SteppedField,
+  LadderBadges,
+  CodeExportModal,
+  RampCurve,
+  MappingChip,
   // Messages
   sendToPlugin,
   createMessageHandler,
@@ -44,9 +52,6 @@ import {
   // Error handling
   safeAsync,
   parseJsonSafe,
-  notifyError,
-  notifySuccess,
-  notifyWarning,
   // Resize
   setDefaultWidth,
   getContentHeight,
@@ -78,6 +83,14 @@ import { sendToPlugin, createMessageHandler } from "figma-plugin-utilities/lib";
 | `LoadingState` | Centred message as `role="status"` (text only, no spinner) |
 | `FieldGroup` | Label + input wrapper; `labelFor` binds the label to a text control |
 | `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 |
+| `FieldGrid` | Fields side by side in equal columns (`columns`, default 2) that shrink below their content |
+| `SteppedField` | A field with − and + icon buttons after it, as one grid cell; `step` event with -1 or 1 |
+| `LadderBadges` | A scale's sizes as badges, outlined where used and archived where not, each with the caller's tooltip |
+| `RampCurve` | A ramp's Bézier at the breakpoint shown, in the caller's units: handles for the ends and the bend at the smallest and largest breakpoint, blends between; `change` and `select` events |
+| `MappingChip` | One side of a source → target row: a filled 24px chip with a lead icon or chit, a truncating label, a `preview` after a dot and a trailing `count`; `click` event |
+| `CodeExportModal` | Read-only code in a modal with a copy button that reads "Copied" for 2s; a `controls` slot above the code |
 
 Every component also takes a `class` (or `className`) prop.
 
@@ -195,6 +208,103 @@ Large checkbox with card-style background and better touch targets.
 </CheckboxCard>
 ```
 
+### FieldGrid
+
+```svelte
+<FieldGrid columns={3}>
+  <FieldGroup label="Base">…</FieldGroup>
+  <FieldGroup label="Ratio">…</FieldGroup>
+  <FieldGroup label="Steps">…</FieldGroup>
+</FieldGrid>
+```
+
+### SteppedField
+
+```svelte
+<SteppedField
+  downLabel="Step {set.name} down"
+  upLabel="Step {set.name} up"
+  on:step={(e) => setOffset(set.offset + e.detail)}
+>
+  <FieldGroup label="Steps off the curve" labelFor="offset" size="small">
+    <NumericInput id="offset" value={set.offset} precision={0} />
+  </FieldGroup>
+</SteppedField>
+```
+
+### LadderBadges
+
+```svelte
+<LadderBadges
+  ariaLabel="Ladder sizes"
+  badges={ladder.map((value, i) => ({
+    value,
+    used: used.has(i),
+    title: used.has(i) ? "Used by a style" : "Unused",
+  }))}
+/>
+```
+
+Each badge's accessible name is `"{value}px, used"` or `"{value}px, unused"`.
+
+### MappingChip
+
+```svelte
+<MappingChip
+  label={row.sourceName}
+  count={row.uses}
+  tone="secondary"
+  title="Select these icons"
+  on:click={() => reveal(row)}
+/>
+```
+
+`iconName` or `chit` (which wins) adds a lead that hangs into the padding; `preview` follows the label as "label · preview"; `tone` is `default`, `secondary` or `component`; `selected` draws the selection border. The `lead` slot takes a marker ahead of the lead, and `element` binds the button.
+
+### RampCurve
+
+```svelte
+<RampCurve
+  {ramp}
+  curves={breakpoints.map((_, b) => rampAt(ramp, b))}
+  span={[lo, hi]}
+  grid={ladder.map((size, rung) => ({ key: rung, y: size, label: size }))}
+  dots={levels.map((size, k) => ({ key: k, x: k / (levels.length - 1), y: size }))}
+  {breakpoints}
+  {selected}
+  rungCount={ladder.length}
+  rungAt={(px) => nearestRung(ladder, px)}
+  format={(px) => `${Math.round(px)}px`}
+  ariaLabel="Heading ramp"
+  bottomLabel="Smallest level"
+  topLabel="Largest level"
+  along="levels"
+  on:change={(e) => (ramp = { ...ramp, ...e.detail })}
+  on:select={(e) => (selected = e.detail)}
+/>
+```
+
+`ramp` holds the ends as rungs and the bends at each end (`bottomSm`, `topSm`, `bendSm`, `bottomLg`, `topLg`, `bendLg`) and `bendPosition`; `change` patches those keys. Everything else on the y axis is in the caller's units.
+
+### CodeExportModal
+
+```svelte
+<CodeExportModal
+  isOpen={exportOpen}
+  title="Export CSS"
+  value={css}
+  ariaLabel="Exported CSS"
+  copyLabel="Copy CSS"
+  onClose={() => (exportOpen = false)}
+>
+  <svelte:fragment slot="controls">
+    <SegmentedControl …/>
+  </svelte:fragment>
+</CodeExportModal>
+```
+
+Copies with `execCommand`, since the plugin iframe isn't granted clipboard-write. `position` (default `"bottom"`), `width` (`"medium"`) and `height` (`"auto"`) pass through to `Modal`.
+
 ## Utilities
 
 ### Messages (`lib/messages.js`)
@@ -260,11 +370,6 @@ if (result.ok) {
 // Parse JSON safely
 const parsed = parseJsonSafe(jsonString);
 // { ok: true, value: {...} } or { ok: false, error: "..." }
-
-// Figma notifications
-notifySuccess("Done!");
-notifyError("Something went wrong");
-notifyWarning("Check your input");
 ```
 
 ### Resize (`lib/resize.js`)
@@ -294,7 +399,7 @@ setDefaultWidth(320);
 
 ### Spec Frame Builders (`lib/figma-frame-builders.ts`)
 
-Typed builders for canvas frames in a spec or documentation generator — auto-layout frames and components, text, token chips, colour swatches, table cells and headers, with light and dark palettes.
+Typed builders for canvas frames in a spec or documentation generator — auto-layout frames and components, text, token chips, color swatches, table cells and headers, with light and dark palettes.
 
 ```typescript
 import {
@@ -312,6 +417,14 @@ row.appendChild(createTokenChip({ label: "#FFFFFF", background: theme.chipBg, te
 
 `specTokens` carries `accentColors`, `fonts` and `themes` (`light`, `dark`). Builders that can return either node take `as: "component"` for a `ComponentNode` instead of a `FrameNode`. Exported types: `PaddingSpec`, `SpecTheme`, `NodeKind`, `NodeFor`.
 
+### Scale Math (`lib/scale.ts`)
+
+Pure math for scales shaped across breakpoints — the ramp's quadratic Bézier (`bezier`, `clampPosition`, `levelT`), blending by viewport width (`blendAt`), values between breakpoints (`valueAtWidth`), fallback widths (`FALLBACK_WIDTHS`, `isBreakpointName`, `widthsFor`) and fluid CSS (`fluidClamp`, `trimNumber`), plus `lerp` and `roundHalfDown`. No Figma API: both threads may import it, provided the plugin builds each thread separately.
+
+```typescript
+import { widthsFor, blendAt, fluidClamp } from "figma-plugin-utilities/lib/scale";
+```
+
 ### Figma Helpers (`lib/figma-helpers.ts`)
 
 For use in `code.ts`:
@@ -321,13 +434,10 @@ import {
   sendToUI,
   showError,
   showSuccess,
-  getCollections,
-  getVariables,
-  getSelection,
   focusNodes,
   loadFont,
-  saveToStorage,
-  loadFromStorage,
+  setText,
+  createSettingsStore,
   handleResize,
 } from "figma-plugin-utilities/lib/figma-helpers";
 
@@ -338,23 +448,21 @@ sendToUI("success", { message: "Done!" });
 showError("Something went wrong");
 showSuccess("Created!");
 
-// Variables
-const collections = await getCollections();
-const colorVars = await getVariables("COLOR");
-
-// Selection
-const selected = getSelection(); // all selected nodes
-const frames = getSelection("FRAME"); // filtered by type
-
 // Focus viewport on nodes
 focusNodes(figma.currentPage.selection);
 
-// Load font before using
+// Load a font before using it (once per run)
 await loadFont("Inter", "Regular");
 
-// Client storage
-await saveToStorage("settings", { theme: "dark" });
-const settings = await loadFromStorage("settings", { theme: "light" });
+// Set a text layer's characters in its own fonts
+await setText(textNode, "Hello");
+
+// Settings in client storage, cleaned on load and on save
+const store = createSettingsStore("settings", (raw) => ({
+  theme: (raw as { theme?: string })?.theme === "dark" ? "dark" : "light",
+}));
+const settings = await store.load();
+await store.save({ ...settings, theme: "dark" });
 
 // Handle resize message from UI (call in your message handler)
 if (msg.type === "resize") handleResize(msg);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-plugin-utilities",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Shared Svelte components and utilities for Figma plugins",
   "type": "module",
   "svelte": "./src/index.js",
@@ -33,6 +33,31 @@
       "types": "./src/lib/figma-frame-builders.ts",
       "import": "./src/lib/figma-frame-builders.ts",
       "default": "./src/lib/figma-frame-builders.ts"
+    },
+    "./lib/figma-variables": {
+      "types": "./src/lib/figma-variables.ts",
+      "import": "./src/lib/figma-variables.ts",
+      "default": "./src/lib/figma-variables.ts"
+    },
+    "./lib/colors": {
+      "types": "./src/lib/colors.ts",
+      "import": "./src/lib/colors.ts",
+      "default": "./src/lib/colors.ts"
+    },
+    "./lib/scale": {
+      "types": "./src/lib/scale.ts",
+      "import": "./src/lib/scale.ts",
+      "default": "./src/lib/scale.ts"
+    },
+    "./lib/format": {
+      "types": "./src/lib/format.ts",
+      "import": "./src/lib/format.ts",
+      "default": "./src/lib/format.ts"
+    },
+    "./lib/confirm": {
+      "types": "./src/lib/confirm.ts",
+      "import": "./src/lib/confirm.ts",
+      "default": "./src/lib/confirm.ts"
     }
   },
   "files": [
@@ -66,7 +91,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.7.0",
     "globals": "^17.12.0",
     "prettier": "^3.9.8",
     "prettier-plugin-svelte": "^3.4.0",

package/src/components/CodeExportModal.svelte

@@ -0,0 +1,98 @@
+<!--
+  Read-only code in a modal, with a button that copies it. Each modal keeps
+  its own "Copied" state, so copying one never marks the other.
+-->
+<script>
+  import { onDestroy } from "svelte";
+  import { Button, Modal, Textarea } from "figma-ui3-kit-svelte";
+
+  export let isOpen = false;
+  export let title;
+  export let value = "";
+  /** Names the code for assistive tech, e.g. "Exported token JSON". */
+  export let ariaLabel;
+  /** The copy button's label, e.g. "Copy JSON". */
+  export let copyLabel;
+  export let position = "bottom";
+  export let width = "medium";
+  export let height = "auto";
+  export let onClose = null;
+
+  let copied = false;
+  let copyTimer = null;
+  onDestroy(() => clearTimeout(copyTimer));
+
+  // Reopened, the button reads as it would before a copy.
+  $: if (isOpen) copied = false;
+
+  // execCommand, not the Clipboard API: the plugin iframe isn't granted
+  // clipboard-write.
+  function handleCopy() {
+    try {
+      const prevActive = document.activeElement;
+      const ta = document.createElement("textarea");
+      ta.value = value;
+      ta.style.position = "fixed";
+      ta.style.left = "-999999px";
+      ta.style.top = "-999999px";
+      document.body.appendChild(ta);
+      ta.focus();
+      ta.select();
+      const ok = document.execCommand("copy");
+      ta.remove();
+      if (prevActive instanceof HTMLElement) prevActive.focus();
+      if (ok) {
+        copied = true;
+        clearTimeout(copyTimer);
+        copyTimer = setTimeout(() => (copied = false), 2000);
+      }
+    } catch {
+      // execCommand unavailable — nothing to do.
+    }
+  }
+</script>
+
+<Modal
+  {isOpen}
+  {title}
+  {position}
+  {width}
+  {height}
+  overlayPadding="0px"
+  {onClose}
+>
+  <div class="export-content">
+    <!-- Options for what's exported, above the code. -->
+    <slot name="controls" />
+    <Textarea {value} readonly {ariaLabel} variant="code" />
+  </div>
+  <svelte:fragment slot="footer-right">
+    <Button variant="primary" on:click={handleCopy}>
+      {copied ? "Copied" : copyLabel}
+    </Button>
+  </svelte:fragment>
+</Modal>
+
+<style>
+  .export-content {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    gap: var(--size-xsmall);
+    min-height: 0;
+  }
+
+  .export-content :global(.textarea) {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+  }
+
+  .export-content :global(textarea) {
+    flex: 1;
+    min-height: 0;
+    resize: none;
+    white-space: pre;
+  }
+</style>

package/src/components/ConfirmModal.svelte

@@ -0,0 +1,66 @@
+<!--
+  The dialog confirmAction() opens: mount one in the plugin's UI, after
+  everything else, so it shows above any modal that asks.
+-->
+<script>
+  import { Modal, Button, Text } from "figma-ui3-kit-svelte";
+  import { confirmRequest, answerConfirm } from "../lib/confirm";
+</script>
+
+<Modal
+  isOpen={!!$confirmRequest}
+  title={$confirmRequest?.title ?? ""}
+  width="small"
+  position="center"
+  on:close={() => answerConfirm(false)}
+>
+  <Text>{$confirmRequest?.message ?? ""}</Text>
+
+  <svelte:fragment slot="footer-full">
+    <div class="confirm-footer">
+      <div class="confirm-actions">
+        <Button variant="secondary" on:click={() => answerConfirm(false)}>
+          {$confirmRequest?.cancelLabel || "Cancel"}
+        </Button>
+        <Button
+          variant={$confirmRequest?.destructive ? "destructive" : "primary"}
+          on:click={() => answerConfirm(true)}
+        >
+          {$confirmRequest?.confirmLabel ?? ""}
+        </Button>
+      </div>
+    </div>
+  </svelte:fragment>
+</Modal>
+
+<style>
+  /* The kit's footer is 40px tall; this one grows with stacked buttons. */
+  :global(.modal-footer:has(.confirm-footer)) {
+    height: auto;
+  }
+
+  /* The footer's width, which the buttons are laid out by. */
+  .confirm-footer {
+    container-type: inline-size;
+  }
+
+  .confirm-actions {
+    display: flex;
+    justify-content: flex-end;
+    gap: var(--size-xxsmall);
+    width: 100%;
+  }
+
+  /* In a narrow window, such as a 240px plugin, the buttons don't fit side
+     by side: they stack at full width, the confirming one on top. */
+  @container (max-width: 215px) {
+    .confirm-actions {
+      flex-direction: column-reverse;
+      align-items: stretch;
+    }
+
+    .confirm-actions > :global(*) {
+      width: 100%;
+    }
+  }
+</style>