figma-plugin-utilities 0.1.0

package/README.md

@@ -0,0 +1,223 @@
+# figma-plugin-utils
+
+Shared Svelte components and utilities for Figma plugins.
+
+## Installation
+
+```bash
+npm install figma-plugin-utils
+```
+
+## Usage
+
+### Import Everything
+
+```javascript
+import {
+  // Components
+  PluginLayout,
+  Header,
+  Footer,
+  StatusBar,
+  EmptyState,
+  ListItem,
+  LoadingState,
+  FieldGroup,
+  // Utilities
+  sendToPlugin,
+  createMessageHandler,
+  rgbToHex,
+  hexToRgb,
+  validateUrl,
+  validateJsonString,
+  sanitizeName,
+} from "figma-plugin-utils";
+```
+
+### Import Specific Modules
+
+```javascript
+// Components only
+import { PluginLayout, Header, Footer } from "figma-plugin-utils/components";
+
+// Utilities only
+import { sendToPlugin, createMessageHandler } from "figma-plugin-utils/lib";
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| `PluginLayout` | Main content wrapper with scrollable area |
+| `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 |
+| `ListItem` | Selectable list items with metadata slot and action menu |
+| `LoadingState` | Centered loading indicator with custom message |
+| `FieldGroup` | Label + input wrapper for form fields |
+
+### Header
+
+```svelte
+<Header title="My Plugin">
+  <svelte:fragment slot="left">
+    <IconButton iconName={IconBack} on:click={goBack} />
+  </svelte:fragment>
+  <svelte:fragment slot="right">
+    <IconButton iconName={IconSettings} />
+  </svelte:fragment>
+</Header>
+
+<!-- Without border -->
+<Header title="Settings" noBorder />
+```
+
+### Footer
+
+```svelte
+<!-- Right-aligned (default) -->
+<Footer>
+  <Button variant="primary">Save</Button>
+</Footer>
+
+<!-- Split layout -->
+<Footer variant="split">
+  <svelte:fragment slot="left">
+    <Button variant="secondary">Cancel</Button>
+  </svelte:fragment>
+  <svelte:fragment slot="right">
+    <Button variant="primary">Save</Button>
+  </svelte:fragment>
+</Footer>
+
+<!-- Full-width buttons -->
+<Footer variant="full">
+  <Button variant="primary">Generate</Button>
+</Footer>
+```
+
+### StatusBar
+
+```svelte
+<StatusBar 
+  message={status.message} 
+  type={status.type} 
+  on:close={() => status = { message: '', type: 'info' }} 
+/>
+```
+
+Types: `info`, `success`, `error`, `warning`. Auto-dismisses after 4s for `info` and `success`.
+
+### EmptyState
+
+```svelte
+<EmptyState
+  message="No items yet"
+  icon="search"
+  actions={[
+    { label: "Add Item", handler: handleAdd },
+    { label: "Import", handler: handleImport }
+  ]}
+/>
+```
+
+### ListItem
+
+```svelte
+<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 metadata</span>
+</ListItem>
+```
+
+## Utilities
+
+### Messages (`lib/messages.js`)
+
+```javascript
+// Send message to plugin code
+sendToPlugin("my-action", { data: "value" });
+
+// Handle messages from plugin
+window.onmessage = createMessageHandler({
+  success: (msg) => console.log("Success:", msg),
+  error: (msg) => console.error("Error:", msg),
+});
+```
+
+### Colors (`lib/colors.js`)
+
+```javascript
+// Convert between formats (Figma uses 0-1 range)
+const rgb = hexToRgb("#FF0000"); // { r: 1, g: 0, b: 0 }
+const hex = rgbToHex({ r: 1, g: 0, b: 0 }); // "#FF0000"
+
+// Calculate contrast
+const ratio = getContrastRatio(color1, color2);
+const passes = meetsContrastLevel(ratio, "AA"); // true/false
+```
+
+### Validation (`lib/validation.js`)
+
+```javascript
+const urlResult = validateUrl("https://example.com");
+// { valid: true } or { valid: false, error: "..." }
+
+const jsonResult = validateJsonString('{"key": "value"}');
+// { valid: true, parsed: {...} } or { valid: false, error: "..." }
+
+const clean = sanitizeName("My Plugin!!!"); // "My Plugin"
+```
+
+### Error Handling (`lib/errorHandling.js`)
+
+```javascript
+// Safe async operations
+const result = await safeAsync(
+  () => fetch(url),
+  "Loading data"
+);
+if (result.ok) {
+  console.log(result.value);
+} else {
+  console.error(result.error.userMessage);
+}
+
+// Parse JSON safely
+const parsed = parseJsonSafe(jsonString);
+// { ok: true, value: {...} } or { ok: false, error: "..." }
+```
+
+### Figma Helpers (`lib/figma-helpers.ts`)
+
+For use in `code.ts`:
+
+```typescript
+import { sendToUI, showError, focusNodes, loadFont } from "figma-plugin-utils/lib/figma-helpers";
+
+// Send message to UI
+sendToUI("success", { message: "Done!" });
+
+// Show notification
+showError("Something went wrong");
+
+// Focus viewport on nodes
+focusNodes(figma.currentPage.selection);
+
+// Load font before using
+await loadFont("Inter", "Regular");
+
+// Client storage
+await saveToStorage("settings", { theme: "dark" });
+const settings = await loadFromStorage("settings", { theme: "light" });
+```

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "figma-plugin-utilities",
+  "version": "0.1.0",
+  "description": "Shared Svelte components and utilities for Figma plugins",
+  "type": "module",
+  "svelte": "./src/index.js",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "exports": {
+    ".": {
+      "svelte": "./src/index.js",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./components": {
+      "svelte": "./src/components/index.js",
+      "import": "./src/components/index.js",
+      "default": "./src/components/index.js"
+    },
+    "./lib": {
+      "import": "./src/lib/index.js",
+      "default": "./src/lib/index.js"
+    },
+    "./lib/figma-helpers": {
+      "types": "./src/lib/figma-helpers.ts",
+      "import": "./src/lib/figma-helpers.ts",
+      "default": "./src/lib/figma-helpers.ts"
+    }
+  },
+  "files": ["src"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mariusroosendaal/figma-plugin-utilities.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mariusroosendaal/figma-plugin-utilities/issues"
+  },
+  "homepage": "https://github.com/mariusroosendaal/figma-plugin-utilities#readme",
+  "keywords": [
+    "figma",
+    "plugin",
+    "svelte",
+    "components",
+    "utilities",
+    "figma-plugin"
+  ],
+  "author": "Marius Roosendaal",
+  "license": "MIT",
+  "dependencies": {
+    "figma-ui3-kit-svelte": "^0.4.0",
+    "svelte": "^4.2.20"
+  }
+}

package/src/components/EmptyState.svelte

@@ -0,0 +1,116 @@
+<script>
+  import { Button, Icon } from "figma-ui3-kit-svelte";
+
+  /**
+   * Empty state display with optional icon and action buttons
+   *
+   * @example
+   * <EmptyState
+   *   message="No items found"
+   *   icon="search"
+   *   actions={[{ label: "Add Item", handler: handleAdd }]}
+   * />
+   */
+
+  /** Message to display */
+  export let message = "";
+
+  /** Optional icon (string name or component) */
+  export let icon = null;
+
+  /** Single action for backward compatibility { label, handler } */
+  export let action = null;
+
+  /** Multiple actions [{ label, handler }] */
+  export let actions = null;
+
+  /** Size variant: 'small', 'medium', 'large' */
+  export let size = "medium";
+
+  /** Whether to center vertically */
+  export let centered = true;
+
+  // Normalize actions
+  $: normalizedActions = actions ? actions : action ? [action] : null;
+</script>
+
+<div
+  class="empty-state"
+  class:centered
+  class:small={size === "small"}
+  class:large={size === "large"}
+>
+  {#if icon}
+    <div class="empty-state__icon">
+      {#if typeof icon === "string"}
+        <Icon iconName={icon} />
+      {:else}
+        <svelte:component this={icon} />
+      {/if}
+    </div>
+  {/if}
+
+  <div class="empty-state__message">
+    {message}
+  </div>
+
+  {#if normalizedActions && normalizedActions.length > 0}
+    <div class="empty-state__actions">
+      {#each normalizedActions as actionItem}
+        <Button variant="secondary" on:click={actionItem.handler}>
+          {actionItem.label}
+        </Button>
+      {/each}
+    </div>
+  {/if}
+</div>
+
+<style>
+  .empty-state {
+    text-align: center;
+    padding: var(--size-xsmall);
+    color: var(--figma-color-text-secondary);
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--size-xsmall);
+    font-family: var(--font-stack);
+    text-wrap: balance;
+    flex: 1;
+  }
+
+  .empty-state.centered {
+    justify-content: center;
+    align-items: center;
+  }
+
+  .empty-state.small {
+    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);
+  }
+
+  .empty-state:not(.small):not(.large) {
+    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);
+  }
+
+  .empty-state.large {
+    font-size: var(--body-large-font-size);
+    font-weight: var(--body-large-font-weight);
+    letter-spacing: var(--body-large-letter-spacing);
+    line-height: var(--body-large-line-height);
+  }
+
+  .empty-state__actions {
+    display: flex;
+    flex-direction: row;
+    gap: var(--size-xxsmall);
+    align-items: center;
+    justify-content: center;
+    flex-wrap: wrap;
+  }
+</style>

package/src/components/FieldGroup.svelte

@@ -0,0 +1,34 @@
+<script>
+  import { Label } from "figma-ui3-kit-svelte";
+
+  /**
+   * Field group wrapper
+   * Wraps a form field with an optional label
+   *
+   * @example
+   * <FieldGroup label="Collection">
+   *   <Dropdown menuItems={options} bind:value={selected} />
+   * </FieldGroup>
+   */
+
+  /** Label text (optional) */
+  export let label = "";
+
+  /** For attribute for the label (optional) */
+  export let labelFor = "";
+</script>
+
+<div class="field-group">
+  {#if label}
+    <Label for={labelFor}>{label}</Label>
+  {/if}
+  <slot />
+</div>
+
+<style>
+  .field-group {
+    display: flex;
+    flex-direction: column;
+    gap: var(--size-xxsmall);
+  }
+</style>

package/src/components/Footer.svelte

@@ -0,0 +1,110 @@
+<script>
+  /**
+   * Plugin footer with layout variants
+   *
+   * @example
+   * <!-- Right-aligned (default) -->
+   * <Footer>
+   *   <Button>Save</Button>
+   * </Footer>
+   *
+   * <!-- Split layout -->
+   * <Footer variant="split">
+   *   <svelte:fragment slot="left">
+   *     <Button variant="secondary">Cancel</Button>
+   *   </svelte:fragment>
+   *   <svelte:fragment slot="right">
+   *     <Button variant="primary">Save</Button>
+   *   </svelte:fragment>
+   * </Footer>
+   *
+   * <!-- Full width buttons -->
+   * <Footer variant="full">
+   *   <Button variant="primary">Create item</Button>
+   * </Footer>
+   */
+
+  /** Layout variant: 'right', 'split', 'full' */
+  export let variant = "right";
+
+  /** Additional CSS class */
+  export let className = "";
+</script>
+
+<div class="footer footer--{variant} {className}">
+  {#if variant === "right"}
+    <div class="footer__right">
+      <slot />
+    </div>
+  {:else if variant === "split"}
+    <div class="footer__left">
+      <slot name="left" />
+    </div>
+    <div class="footer__right">
+      <slot name="right" />
+    </div>
+  {:else if variant === "full"}
+    <slot />
+  {/if}
+</div>
+
+<style>
+  .footer {
+    height: var(--size-large);
+    bottom: 0;
+    left: 0;
+    right: 0;
+    display: flex;
+    gap: var(--size-xxsmall);
+    padding: var(--size-xxsmall);
+    border-top: 1px solid var(--figma-color-border);
+    background: var(--figma-color-bg);
+    z-index: 10;
+  }
+
+  .footer :global(> *),
+  .footer :global(> * > *) {
+    display: flex;
+    gap: var(--size-xxsmall);
+    align-items: center;
+    min-width: 0;
+  }
+
+  .footer--right {
+    justify-content: flex-end;
+  }
+
+  .footer--right .footer__right {
+    display: flex;
+    gap: var(--size-xxsmall);
+    align-items: center;
+  }
+
+  .footer--split {
+    justify-content: space-between;
+  }
+
+  .footer--split .footer__left {
+    display: flex;
+    gap: var(--size-xxsmall);
+    align-items: center;
+    flex: 1;
+  }
+
+  .footer--split .footer__right {
+    display: flex;
+    gap: var(--size-xxsmall);
+    align-items: center;
+    justify-content: end;
+  }
+
+  .footer--full {
+    display: flex;
+    width: 100%;
+  }
+
+  .footer--full :global(button) {
+    flex: 1;
+    width: 100%;
+  }
+</style>

package/src/components/Header.svelte

@@ -0,0 +1,81 @@
+<script>
+  // Header component with left/center/right slots
+
+  /** Additional CSS class */
+  export let className = "";
+
+  /** Title text (displayed in left section) */
+  export let title = "";
+
+  /** Remove bottom border */
+  export let noBorder = false;
+</script>
+
+<div
+  class="header {className}"
+  class:has-left-content={$$slots.left}
+  class:no-border={noBorder}
+>
+  <div class="header__left">
+    <slot name="left" />
+    {#if title}
+      <h2 class="header__title">{title}</h2>
+    {/if}
+  </div>
+  <div class="header__center">
+    <slot name="center" />
+  </div>
+  <div class="header__right">
+    <slot name="right" />
+  </div>
+</div>
+
+<style>
+  .header {
+    height: var(--size-large);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0 var(--size-xxsmall) 0 var(--size-xsmall);
+    border-bottom: 1px solid var(--figma-color-border);
+    background: var(--figma-color-bg);
+    gap: var(--size-xsmall);
+  }
+
+  .header.has-left-content {
+    padding-left: var(--size-xxsmall);
+  }
+
+  .header.no-border {
+    border-bottom: none;
+  }
+
+  .header__left {
+    display: flex;
+    align-items: center;
+    gap: var(--size-xxsmall);
+  }
+
+  .header__center {
+    flex: 1;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  .header__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);
+    color: var(--figma-color-text);
+    margin: 0;
+  }
+
+  .header__right {
+    display: flex;
+    align-items: center;
+    gap: var(--size-xxsmall);
+    position: relative;
+  }
+</style>