@figma-vars/hooks 1.0.5 → 1.0.9

package/dist/constants/index.d.ts

@@ -0,0 +1,11 @@
+export declare const FIGMA_API_BASE_URL = "https://api.figma.com";
+export declare const FIGMA_FILES_ENDPOINT = "https://api.figma.com/v1/files";
+export declare const FIGMA_VARIABLES_ENDPOINT: (fileKey: string) => string;
+export declare const FIGMA_COLLECTIONS_ENDPOINT: (fileKey: string) => string;
+export declare const CREATE_VARIABLE_ACTION = "CREATE";
+export declare const UPDATE_VARIABLE_ACTION = "UPDATE";
+export declare const DELETE_VARIABLE_ACTION = "DELETE";
+export declare const DEFAULT_HEADERS: {
+    'Content-Type': string;
+};
+export declare const DEFAULT_ERROR_MESSAGE = "An error occurred while communicating with the Figma API.";

package/dist/experimental/usePublishVars.d.ts

@@ -0,0 +1,2 @@
+declare const usePublishVars: () => {};
+export default usePublishVars;

package/dist/experimental/useSync.d.ts

@@ -0,0 +1,2 @@
+declare const useSync: () => {};
+export default useSync;

package/dist/experimental/useVariableAliases.d.ts

@@ -0,0 +1,9 @@
+import { FigmaVariable } from 'types';
+declare const useVariableAliases: () => {
+    aliases: {
+        [alias: string]: FigmaVariable;
+    };
+    setAlias: (alias: string, variable: FigmaVariable) => void;
+    removeAlias: (alias: string) => void;
+};
+export default useVariableAliases;

package/dist/experimental/useVariableBindings.d.ts

@@ -0,0 +1,7 @@
+import { FigmaVariable } from 'types';
+declare const useVariableBindings: () => {
+    bindings: Map<string, FigmaVariable>;
+    bindVariable: (elementId: string, variable: FigmaVariable) => void;
+    unbindVariable: (elementId: string) => void;
+};
+export default useVariableBindings;

package/dist/figma-vars-hooks.js

@@ -0,0 +1,222 @@
+var E = Object.defineProperty;
+var k = (t, e, r) => e in t ? E(t, e, { enumerable: !0, configurable: !0, writable: !0, value: r }) : t[e] = r;
+var w = (t, e, r) => k(t, typeof e != "symbol" ? e + "" : e, r);
+import { useState as i, useEffect as d, useRef as F, useCallback as p } from "react";
+const c = () => {
+  const [t, e] = i("");
+  return d(() => {
+    e("");
+  }, []), t;
+}, A = (t, e) => {
+  const [r, a] = i(null), [n, s] = i(!0), [o, l] = i(null), h = c(), m = F(null), u = p(async () => {
+    if (!h) {
+      l(new Error("API token is not provided")), s(!1);
+      return;
+    }
+    s(!0), l(null);
+    try {
+      const f = `https://api.figma.com/v1/files/${t}/variables`, b = await fetch(f, {
+        method: "GET",
+        headers: {
+          "X-FIGMA-TOKEN": h
+        }
+      });
+      if (!b.ok)
+        throw new Error(
+          `Failed to fetch Figma variables: ${b.statusText}`
+        );
+      const g = await b.json();
+      a(g.meta.variables);
+    } catch (f) {
+      l(
+        f instanceof Error ? f : new Error("Failed to fetch variables")
+      );
+    } finally {
+      s(!1);
+    }
+  }, [t, h]), v = p(() => {
+    u();
+  }, [u]);
+  return d(() => {
+    if (u(), e != null && e.pollInterval)
+      return m.current = setInterval(u, e.pollInterval), () => {
+        m.current && clearInterval(m.current);
+      };
+  }, [u, e == null ? void 0 : e.pollInterval]), { variables: r, loading: n, error: o, refresh: v };
+}, V = (t) => {
+  const [e, r] = i({
+    data: null,
+    loading: !0,
+    error: null
+  }), a = c();
+  return d(() => {
+    (async () => {
+      if (!a) {
+        r((o) => ({
+          ...o,
+          loading: !1,
+          error: new Error("API token is not provided")
+        }));
+        return;
+      }
+      const s = `https://api.figma.com/v1/files/${t}/variable_collections`;
+      try {
+        const o = await fetch(s, {
+          headers: {
+            "X-FIGMA-TOKEN": a
+          }
+        });
+        if (!o.ok)
+          throw new Error(
+            `Failed to fetch Figma collections: ${o.statusText}`
+          );
+        const l = await o.json();
+        r({
+          data: l.meta.variableCollections,
+          loading: !1,
+          error: null
+        });
+      } catch (o) {
+        r((l) => ({
+          ...l,
+          loading: !1,
+          error: o instanceof Error ? o : new Error("Failed to fetch")
+        }));
+      }
+    })();
+  }, [t, a]), e;
+}, I = (t) => {
+  const [e, r] = i(null), a = c();
+  return d(() => {
+    (async () => {
+      const s = `https://api.figma.com/v1/collections/${t}/modes`;
+      try {
+        if (!(await fetch(s, {
+          headers: {
+            "X-FIGMA-TOKEN": a
+          }
+        })).ok) throw new Error("Failed to fetch Figma modes");
+        r({ success: !0, message: "Modes fetched successfully" });
+      } catch (o) {
+        r({
+          success: !1,
+          message: o instanceof Error ? o.message : "Unknown error"
+        });
+      }
+    })();
+  }, [t, a]), { response: e };
+};
+async function M(t, e) {
+  const r = c();
+  if (!r) throw new Error("API token is not provided");
+  const a = `https://api.figma.com/v1/files/${t}/variables`, n = await fetch(a, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-FIGMA-TOKEN": r
+    },
+    body: JSON.stringify(e)
+  });
+  if (!n.ok)
+    throw new Error("Failed to create Figma variable");
+  return n.json();
+}
+async function O(t, e, r) {
+  const a = c();
+  if (!a) throw new Error("API token is not provided");
+  const n = `https://api.figma.com/v1/files/${t}/variables/${e}`, s = await fetch(n, {
+    method: "PUT",
+    headers: {
+      "Content-Type": "application/json",
+      "X-FIGMA-TOKEN": a
+    },
+    body: JSON.stringify(r)
+  });
+  if (!s.ok)
+    throw new Error("Failed to update Figma variable");
+  return s.json();
+}
+async function P(t, e) {
+  const r = c();
+  if (!r) throw new Error("API token is not provided");
+  const a = `https://api.figma.com/v1/files/${t}/variables/${e}`, n = await fetch(a, {
+    method: "DELETE",
+    headers: {
+      "X-FIGMA-TOKEN": r
+    }
+  });
+  if (!n.ok)
+    throw new Error("Failed to delete Figma variable");
+  return n.json();
+}
+async function $(t, e) {
+  const r = c();
+  if (!r) throw new Error("API token is not provided");
+  const a = `https://api.figma.com/v1/variables/${t}/values`, n = await fetch(a, {
+    method: "PUT",
+    headers: {
+      "X-FIGMA-TOKEN": r,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(e)
+  });
+  if (!n.ok)
+    throw new Error("Failed to update variable values");
+  return n.json();
+}
+function j(t, e) {
+  return t.filter((r) => {
+    let a = !0;
+    return e.type && (a = a && r.type === e.type), e.name && (a = a && r.name === e.name), a;
+  });
+}
+class N {
+  constructor() {
+    w(this, "cache", {});
+  }
+  get(e) {
+    return this.cache[e];
+  }
+  set(e, r) {
+    this.cache[e] = r;
+  }
+  clear(e) {
+    e ? delete this.cache[e] : this.cache = {};
+  }
+}
+const C = () => null, G = () => !0, S = async (t, e = { method: "GET" }) => {
+  throw new Error("Figma API token is not available.");
+}, X = () => {
+  const [t, e] = i({});
+  return { aliases: t, setAlias: (n, s) => e((o) => ({ ...o, [n]: s })), removeAlias: (n) => {
+    const s = { ...t };
+    delete s[n], e(s);
+  } };
+}, K = () => {
+  const [t, e] = i(
+    /* @__PURE__ */ new Map()
+  );
+  return { bindings: t, bindVariable: (n, s) => e(new Map(t.set(n, s))), unbindVariable: (n) => {
+    const s = new Map(t);
+    s.delete(n), e(s);
+  } };
+}, x = () => ({}), B = () => ({});
+export {
+  N as VariablesCache,
+  M as createVariable,
+  P as deleteVariable,
+  S as fetchWithAuth,
+  j as filterVariables,
+  C as getFigmaToken,
+  O as updateVariable,
+  $ as updateVariableValues,
+  c as useFigmaToken,
+  x as usePublishVars,
+  B as useSync,
+  X as useVariableAliases,
+  K as useVariableBindings,
+  V as useVariableCollections,
+  I as useVariableModes,
+  A as useVariables,
+  G as validateToken
+};

package/dist/figma-vars-hooks.umd.cjs

@@ -0,0 +1 @@
+(function(t,s){typeof exports=="object"&&typeof module<"u"?s(exports,require("react")):typeof define=="function"&&define.amd?define(["exports","react"],s):(t=typeof globalThis<"u"?globalThis:t||self,s(t.FigmaVarsHooks={},t.react))})(this,function(t,s){"use strict";var N=Object.defineProperty;var G=(t,s,c)=>s in t?N(t,s,{enumerable:!0,configurable:!0,writable:!0,value:c}):t[s]=c;var w=(t,s,c)=>G(t,typeof s!="symbol"?s+"":s,c);const c=()=>{const[a,e]=s.useState("");return s.useEffect(()=>{e("")},[]),a},g=(a,e)=>{const[n,r]=s.useState(null),[o,i]=s.useState(!0),[l,u]=s.useState(null),h=c(),b=s.useRef(null),f=s.useCallback(async()=>{if(!h){u(new Error("API token is not provided")),i(!1);return}i(!0),u(null);try{const d=`https://api.figma.com/v1/files/${a}/variables`,m=await fetch(d,{method:"GET",headers:{"X-FIGMA-TOKEN":h}});if(!m.ok)throw new Error(`Failed to fetch Figma variables: ${m.statusText}`);const $=await m.json();r($.meta.variables)}catch(d){u(d instanceof Error?d:new Error("Failed to fetch variables"))}finally{i(!1)}},[a,h]),O=s.useCallback(()=>{f()},[f]);return s.useEffect(()=>{if(f(),e!=null&&e.pollInterval)return b.current=setInterval(f,e.pollInterval),()=>{b.current&&clearInterval(b.current)}},[f,e==null?void 0:e.pollInterval]),{variables:n,loading:o,error:l,refresh:O}},v=a=>{const[e,n]=s.useState({data:null,loading:!0,error:null}),r=c();return s.useEffect(()=>{(async()=>{if(!r){n(l=>({...l,loading:!1,error:new Error("API token is not provided")}));return}const i=`https://api.figma.com/v1/files/${a}/variable_collections`;try{const l=await fetch(i,{headers:{"X-FIGMA-TOKEN":r}});if(!l.ok)throw new Error(`Failed to fetch Figma collections: ${l.statusText}`);const u=await l.json();n({data:u.meta.variableCollections,loading:!1,error:null})}catch(l){n(u=>({...u,loading:!1,error:l instanceof Error?l:new Error("Failed to fetch")}))}})()},[a,r]),e},E=a=>{const[e,n]=s.useState(null),r=c();return s.useEffect(()=>{(async()=>{const i=`https://api.figma.com/v1/collections/${a}/modes`;try{if(!(await fetch(i,{headers:{"X-FIGMA-TOKEN":r}})).ok)throw new Error("Failed to fetch Figma modes");n({success:!0,message:"Modes fetched successfully"})}catch(l){n({success:!1,message:l instanceof Error?l.message:"Unknown error"})}})()},[a,r]),{response:e}};async function k(a,e){const n=c();if(!n)throw new Error("API token is not provided");const r=`https://api.figma.com/v1/files/${a}/variables`,o=await fetch(r,{method:"POST",headers:{"Content-Type":"application/json","X-FIGMA-TOKEN":n},body:JSON.stringify(e)});if(!o.ok)throw new Error("Failed to create Figma variable");return o.json()}async function V(a,e,n){const r=c();if(!r)throw new Error("API token is not provided");const o=`https://api.figma.com/v1/files/${a}/variables/${e}`,i=await fetch(o,{method:"PUT",headers:{"Content-Type":"application/json","X-FIGMA-TOKEN":r},body:JSON.stringify(n)});if(!i.ok)throw new Error("Failed to update Figma variable");return i.json()}async function p(a,e){const n=c();if(!n)throw new Error("API token is not provided");const r=`https://api.figma.com/v1/files/${a}/variables/${e}`,o=await fetch(r,{method:"DELETE",headers:{"X-FIGMA-TOKEN":n}});if(!o.ok)throw new Error("Failed to delete Figma variable");return o.json()}async function T(a,e){const n=c();if(!n)throw new Error("API token is not provided");const r=`https://api.figma.com/v1/variables/${a}/values`,o=await fetch(r,{method:"PUT",headers:{"X-FIGMA-TOKEN":n,"Content-Type":"application/json"},body:JSON.stringify(e)});if(!o.ok)throw new Error("Failed to update variable values");return o.json()}function y(a,e){return a.filter(n=>{let r=!0;return e.type&&(r=r&&n.type===e.type),e.name&&(r=r&&n.name===e.name),r})}class F{constructor(){w(this,"cache",{})}get(e){return this.cache[e]}set(e,n){this.cache[e]=n}clear(e){e?delete this.cache[e]:this.cache={}}}const A=()=>null,I=()=>!0,S=async(a,e={method:"GET"})=>{throw new Error("Figma API token is not available.")},M=()=>{const[a,e]=s.useState({});return{aliases:a,setAlias:(o,i)=>e(l=>({...l,[o]:i})),removeAlias:o=>{const i={...a};delete i[o],e(i)}}},P=()=>{const[a,e]=s.useState(new Map);return{bindings:a,bindVariable:(o,i)=>e(new Map(a.set(o,i))),unbindVariable:o=>{const i=new Map(a);i.delete(o),e(i)}}},j=()=>({}),C=()=>({});t.VariablesCache=F,t.createVariable=k,t.deleteVariable=p,t.fetchWithAuth=S,t.filterVariables=y,t.getFigmaToken=A,t.updateVariable=V,t.updateVariableValues=T,t.useFigmaToken=c,t.usePublishVars=j,t.useSync=C,t.useVariableAliases=M,t.useVariableBindings=P,t.useVariableCollections=v,t.useVariableModes=E,t.useVariables=g,t.validateToken=I,Object.defineProperty(t,Symbol.toStringTag,{value:"Module"})});

package/dist/hooks/useFigmaToken.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Retrieves the Figma API token from environment or context (future-proofed for provider override)
+ */
+declare const useFigmaToken: () => string;
+export default useFigmaToken;

package/dist/hooks/useVariableCollections.d.ts

@@ -0,0 +1,3 @@
+import { FigmaCollection, HookState } from 'types';
+declare const useVariableCollections: (fileKey: string) => HookState<FigmaCollection[]>;
+export default useVariableCollections;

package/dist/hooks/useVariableModes.d.ts

@@ -0,0 +1,5 @@
+import { FigmaOperationResponse } from 'types';
+declare const useVariableModes: (collectionId: string) => {
+    response: FigmaOperationResponse | null;
+};
+export default useVariableModes;

package/dist/hooks/useVariables.d.ts

@@ -0,0 +1,16 @@
+import { FigmaVariable } from 'types';
+/**
+ * Fetches Figma variables for a given document (file) ID.
+ * Supports polling and manual refresh.
+ * @param documentId - The Figma file ID
+ * @param options - { pollInterval?: number }
+ */
+declare const useVariables: (documentId: string, options?: {
+    pollInterval?: number;
+}) => {
+    variables: FigmaVariable[] | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => void;
+};
+export default useVariables;

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { default as useFigmaToken } from './hooks/useFigmaToken';
+export { default as useVariables } from './hooks/useVariables';
+export { default as useVariableCollections } from './hooks/useVariableCollections';
+export { default as useVariableModes } from 'hooks/useVariableModes';
+export * from 'mutations/createVariable';
+export * from 'mutations/updateVariable';
+export * from 'mutations/deleteVariable';
+export * from 'mutations/updateVariableValues';
+export * from 'utils/filterVariables';
+export * from 'utils/cache';
+export * from 'utils/fetchHelpers';
+export * from 'utils/authHelpers';
+export { default as useVariableAliases } from 'experimental/useVariableAliases';
+export { default as useVariableBindings } from 'experimental/useVariableBindings';
+export { default as usePublishVars } from 'experimental/usePublishVars';
+export { default as useSync } from 'experimental/useSync';

package/dist/mutations/createVariable.d.ts

@@ -0,0 +1,8 @@
+import { FigmaOperationResponse } from 'types';
+/**
+ * Create a new Figma variable in a file.
+ * @param fileKey The Figma file ID
+ * @param variableData The variable data (see Figma Variables API)
+ * @returns Promise<FigmaOperationResponse>
+ */
+export declare function createVariable(fileKey: string, variableData: any): Promise<FigmaOperationResponse>;

package/dist/mutations/deleteVariable.d.ts

@@ -0,0 +1,8 @@
+import { FigmaOperationResponse } from 'types';
+/**
+ * Delete a Figma variable from a file.
+ * @param fileKey The Figma file ID
+ * @param variableId The variable ID
+ * @returns Promise<FigmaOperationResponse>
+ */
+export declare function deleteVariable(fileKey: string, variableId: string): Promise<FigmaOperationResponse>;

package/dist/mutations/updateVariable.d.ts

@@ -0,0 +1,9 @@
+import { FigmaOperationResponse } from 'types';
+/**
+ * Update an existing Figma variable in a file.
+ * @param fileKey The Figma file ID
+ * @param variableId The variable ID
+ * @param newVariableData The new variable data (see Figma Variables API)
+ * @returns Promise<FigmaOperationResponse>
+ */
+export declare function updateVariable(fileKey: string, variableId: string, newVariableData: any): Promise<FigmaOperationResponse>;

package/dist/mutations/updateVariableValues.d.ts

@@ -0,0 +1,8 @@
+import { FigmaOperationResponse } from 'types';
+/**
+ * Update a variable's value across modes (Figma Variables API).
+ * @param variableId The variable ID
+ * @param values The new values for each mode
+ * @returns Promise<FigmaOperationResponse>
+ */
+export declare function updateVariableValues(variableId: string, values: any): Promise<FigmaOperationResponse>;

package/dist/types/figma.d.ts

@@ -0,0 +1,20 @@
+export interface FigmaVariable {
+    id: string;
+    name: string;
+    type: string;
+    description?: string;
+}
+export interface FigmaCollection {
+    id: string;
+    name: string;
+    variables: FigmaVariable[];
+}
+export interface VariablesResponse {
+    meta: {
+        variables: FigmaVariable[];
+    };
+}
+export interface FigmaError {
+    statusCode: number;
+    message: string;
+}

package/dist/types/hooks.d.ts

@@ -0,0 +1,10 @@
+export interface HookState<T> {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+}
+export interface SyncStatus {
+    isSyncing: boolean;
+    lastSynced: Date | null;
+    error: string | null;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './figma';
+export * from './hooks';
+export * from './mutations';

package/dist/types/mutations.d.ts

@@ -0,0 +1,9 @@
+export interface FigmaOperationResponse {
+    success: boolean;
+    message?: string;
+}
+export interface VariableValueUpdate {
+    modeId: string;
+    value: string;
+}
+export type SpecificType = VariableValueUpdate[];

package/dist/utils/authHelpers.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Retrieves the Figma API token from environment variables or any other secure storage mechanism you've implemented.
+ */
+export declare const getFigmaToken: () => string | null;
+/**
+ * Placeholder for a more complex token validation or renewal logic, if needed.
+ */
+export declare const validateToken: () => boolean;

package/dist/utils/cache.d.ts

@@ -0,0 +1,7 @@
+import { FigmaVariable } from 'types';
+export declare class VariablesCache {
+    private cache;
+    get(fileKey: string): FigmaVariable[] | undefined;
+    set(fileKey: string, variables: FigmaVariable[]): void;
+    clear(fileKey?: string): void;
+}

package/dist/utils/fetchHelpers.d.ts

@@ -0,0 +1,10 @@
+interface FetchOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    body?: BodyInit | null;
+    headers?: HeadersInit;
+}
+/**
+ * A helper function for making authenticated fetch requests to the Figma API.
+ */
+export declare const fetchWithAuth: (endpoint: string, options?: FetchOptions) => Promise<any>;
+export {};

package/dist/utils/filterVariables.d.ts

@@ -0,0 +1,5 @@
+import { FigmaVariable } from 'types';
+export declare function filterVariables(variables: FigmaVariable[], criteria: {
+    type?: string;
+    name?: string;
+}): FigmaVariable[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figma-vars/hooks",
-  "version": "1.0.5",
+  "version": "1.0.9",
   "description": "Typed React hooks for managing Figma Variables, modes, tokens, and bindings via API.",
   "author": "Mark Learst",
   "license": "MIT",