@figma-vars/hooks 3.0.0-beta.1 → 3.1.0

package/dist/api/fetcher.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Options for configuring fetcher behavior.
+ *
+ * @public
+ */
+export interface FetcherOptions {
+    /**
+     * Optional AbortSignal to cancel the request.
+     */
+    signal?: AbortSignal;
+    /**
+     * Optional timeout in milliseconds. Creates an AbortSignal internally if provided.
+     */
+    timeout?: number;
+    /**
+     * Optional fetch implementation override (useful for testing or custom fetch implementations).
+     */
+    fetch?: typeof fetch;
+}
 /**
  * Low-level utility to fetch data from the Figma Variables REST API with authentication.
  *
@@ -6,13 +25,17 @@
  * Parses JSON responses and throws detailed errors for failed requests.
  * Intended for internal use by hooks but can be used directly for custom API interactions.
  *
+ * Supports request cancellation via AbortSignal and timeout handling.
+ *
  * @param url - The full Figma REST API endpoint URL (e.g., 'https://api.figma.com/v1/files/{file_key}/variables').
  * @param token - Figma Personal Access Token (PAT) for authentication.
+ * @param options - Optional configuration for abort signal, timeout, or custom fetch implementation.
  *
  * @returns A Promise resolving to the parsed JSON response from the Figma API.
  *
  * @throws Throws an Error if the token is not provided.
  * @throws Throws an Error if the HTTP response is not ok, including the message returned by the Figma API or a default error message.
+ * @throws Throws an AbortError if the request is aborted or times out.
  *
  * @example
  * ```ts
@@ -23,7 +46,15 @@
  *   const data = await fetcher(url, token);
  *   return data;
  * }
+ *
+ * // With timeout:
+ * const data = await fetcher(url, token, { timeout: 5000 });
+ *
+ * // With abort signal:
+ * const controller = new AbortController();
+ * const data = await fetcher(url, token, { signal: controller.signal });
+ * controller.abort(); // Cancel the request
  * ```
  */
-export declare function fetcher<TResponse = unknown>(url: string, token: string): Promise<TResponse>;
+export declare function fetcher<TResponse = unknown>(url: string, token: string, options?: FetcherOptions): Promise<TResponse>;
 //# sourceMappingURL=fetcher.d.ts.map

package/dist/api/fetcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetcher.d.ts","sourceRoot":"","sources":["../../src/api/fetcher.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,OAAO,CAAC,SAAS,GAAG,OAAO,EAC/C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,SAAS,CAAC,CA2BpB"}
+{"version":3,"file":"fetcher.d.ts","sourceRoot":"","sources":["../../src/api/fetcher.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAsB,OAAO,CAAC,SAAS,GAAG,OAAO,EAC/C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC,CA0FpB"}

package/dist/api/index.d.ts

@@ -23,4 +23,6 @@
  */
 export { fetcher } from './fetcher';
 export { mutator } from './mutator';
+export type { FetcherOptions } from './fetcher';
+export type { MutatorOptions } from './mutator';
 //# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACrC,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjD,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA"}

package/dist/api/mutator.d.ts

@@ -1,4 +1,23 @@
-import { VariableAction } from '../types/mutations';
+import { VariableAction, BulkUpdatePayload } from '../types/mutations.js';
+/**
+ * Options for configuring mutator behavior.
+ *
+ * @public
+ */
+export interface MutatorOptions {
+    /**
+     * Optional AbortSignal to cancel the request.
+     */
+    signal?: AbortSignal;
+    /**
+     * Optional timeout in milliseconds. Creates an AbortSignal internally if provided.
+     */
+    timeout?: number;
+    /**
+     * Optional fetch implementation override (useful for testing or custom fetch implementations).
+     */
+    fetch?: typeof fetch;
+}
 /**
  * Low-level utility to send authenticated POST, PUT, or DELETE requests to the Figma Variables REST API.
  *
@@ -7,28 +26,36 @@ import { VariableAction } from '../types/mutations';
  * It handles JSON serialization of the request body, parses JSON responses, and propagates detailed errors.
  * Intended primarily for internal use by mutation hooks, but also suitable for direct custom API mutations.
  *
- * @typeParam T - The expected response type returned from the Figma API.
+ * Supports request cancellation via AbortSignal and timeout handling.
+ *
+ * @typeParam TResponse - The expected response type returned from the Figma API.
  * @param url - The full Figma REST API endpoint URL (e.g., 'https://api.figma.com/v1/files/{file_key}/variables').
  * @param token - Figma Personal Access Token (PAT) used for authentication.
  * @param action - The action for the mutation: 'CREATE', 'UPDATE', or 'DELETE'.
- * @param body - Optional request payload sent as a JSON string.
+ * @param body - Optional request payload. For bulk operations, use BulkUpdatePayload. For individual operations, use objects with `variables` array.
+ * @param options - Optional configuration for abort signal, timeout, or custom fetch implementation.
  *
  * @returns A Promise resolving to the parsed JSON response from the Figma API.
  *
- * @throws Throws an Error if the token is not provided.
- * @throws Throws an Error if the HTTP response is unsuccessful, including the error message from the API or a default message.
+ * @throws Throws a FigmaApiError if the token is not provided or if the HTTP response is unsuccessful.
+ * @throws Throws an AbortError if the request is aborted or times out.
  *
  * @example
  * ```ts
  * import { mutator } from '@figma-vars/hooks/api';
  *
  * async function updateVariable(fileKey: string, token: string, variableId: string) {
- *   const url = `https://api.figma.com/v1/files/${fileKey}/variables/${variableId}`;
- *   const payload = { name: 'Updated Name' };
- *   const result = await mutator(url, token, 'PUT', payload);
+ *   const url = `https://api.figma.com/v1/files/${fileKey}/variables`;
+ *   const payload = { variables: [{ action: 'UPDATE', id: variableId, name: 'Updated Name' }] };
+ *   const result = await mutator(url, token, 'UPDATE', payload);
  *   return result;
  * }
+ *
+ * // With timeout:
+ * const result = await mutator(url, token, 'UPDATE', payload, { timeout: 5000 });
  * ```
  */
-export declare function mutator<TResponse = unknown, TBody extends Record<string, unknown> = Record<string, unknown>>(url: string, token: string, action: VariableAction, body?: TBody): Promise<TResponse>;
+export declare function mutator<TResponse = unknown>(url: string, token: string, action: VariableAction, body?: BulkUpdatePayload | {
+    variables?: Array<Record<string, unknown>>;
+} | Record<string, unknown>, options?: MutatorOptions): Promise<TResponse>;
 //# sourceMappingURL=mutator.d.ts.map

package/dist/api/mutator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mutator.d.ts","sourceRoot":"","sources":["../../src/api/mutator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,OAAO,CAAC,SAAS,GAAG,OAAO,EAAE,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChH,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,cAAc,EACtB,IAAI,CAAC,EAAE,KAAK,GACX,OAAO,CAAC,SAAS,CAAC,CAqCpB"}
+{"version":3,"file":"mutator.d.ts","sourceRoot":"","sources":["../../src/api/mutator.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAG3E;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,OAAO,CAAC,SAAS,GAAG,OAAO,EAC/C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,cAAc,EACtB,IAAI,CAAC,EACD,iBAAiB,GACjB;IAAE,SAAS,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,GAC9C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,SAAS,CAAC,CAyGpB"}

package/dist/constants/index.d.ts

@@ -11,34 +11,8 @@
  */
 export declare const FIGMA_API_BASE_URL = "https://api.figma.com";
 export declare const FIGMA_FILES_ENDPOINT = "https://api.figma.com/v1/files";
-/**
- * Builds the Figma Variables endpoint URL for a given file key.
- *
- * @param fileKey - The unique key of the Figma file.
- * @returns The URL string to access variables in the specified file.
- *
- * @example
- * ```ts
- * const url = FIGMA_VARIABLES_ENDPOINT('your-file-key')
- * ```
- */
-export declare const FIGMA_VARIABLES_ENDPOINT: (fileKey: string) => string;
-/**
- * The base endpoint for creating new variables via POST requests.
- */
-export declare const FIGMA_POST_VARIABLES_ENDPOINT = "https://api.figma.com/v1/variables";
-/**
- * Builds the URL to access a specific Figma variable by its ID.
- *
- * @param variableId - The unique ID of the Figma variable.
- * @returns The URL string to access the variable.
- *
- * @example
- * ```ts
- * const url = FIGMA_VARIABLE_BY_ID_ENDPOINT('variable-id')
- * ```
- */
-export declare const FIGMA_VARIABLE_BY_ID_ENDPOINT: (variableId: string) => string;
+export declare const FIGMA_PUBLISHED_VARIABLES_PATH: (fileKey: string) => string;
+export declare const FIGMA_FILE_VARIABLES_PATH: (fileKey: string) => string;
 /**
  * Builds the URL to fetch local variables for a given Figma file.
  *

package/dist/constants/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/constants/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,kBAAkB,0BAA0B,CAAC;AAE1D,eAAO,MAAM,oBAAoB,mCAAmC,CAAC;AAIrE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,SAAS,MAAM,WACR,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,6BAA6B,uCAAmC,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,6BAA6B,GAAI,YAAY,MAAM,WACX,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,GAAI,SAAS,MAAM,WACR,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,iBAAiB,qBAAqB,CAAC;AAEpD;;GAEG;AACH,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,wBAAwB,mCAAmC,CAAC;AAEzE;;GAEG;AACH,eAAO,MAAM,iCAAiC,8DAA2D,CAAC;AAE1G;;GAEG;AACH,eAAO,MAAM,4BAA4B,mCAAmC,CAAC;AAE7E;;GAEG;AACH,eAAO,MAAM,gCAAgC,qCAAqC,CAAC;AAEnF;;GAEG;AACH,eAAO,MAAM,gCAAgC,qCAAqC,CAAC;AAEnF;;GAEG;AACH,eAAO,MAAM,gCAAgC,qCAAqC,CAAC;AAEnF;;GAEG;AACH,eAAO,MAAM,iCAAiC,8DACe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/constants/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,kBAAkB,0BAA0B,CAAA;AAEzD,eAAO,MAAM,oBAAoB,mCAAmC,CAAA;AAEpE,eAAO,MAAM,8BAA8B,GAAI,SAAS,MAAM,WAClB,CAAA;AAE5C,eAAO,MAAM,yBAAyB,GAAI,SAAS,MAAM,WACvB,CAAA;AAElC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,GAAI,SAAS,MAAM,WACR,CAAA;AAEtD;;GAEG;AACH,eAAO,MAAM,iBAAiB,qBAAqB,CAAA;AAEnD;;GAEG;AACH,eAAO,MAAM,kBAAkB,kBAAkB,CAAA;AAEjD;;GAEG;AACH,eAAO,MAAM,wBAAwB,mCAAmC,CAAA;AAExE;;GAEG;AACH,eAAO,MAAM,iCAAiC,8DAA2D,CAAA;AAEzG;;GAEG;AACH,eAAO,MAAM,4BAA4B,mCAAmC,CAAA;AAE5E;;GAEG;AACH,eAAO,MAAM,gCAAgC,qCACT,CAAA;AAEpC;;GAEG;AACH,eAAO,MAAM,gCAAgC,qCACT,CAAA;AAEpC;;GAEG;AACH,eAAO,MAAM,gCAAgC,qCACT,CAAA;AAEpC;;GAEG;AACH,eAAO,MAAM,iCAAiC,8DACe,CAAA"}

package/dist/contexts/FigmaTokenContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FigmaTokenContext.d.ts","sourceRoot":"","sources":["../../src/contexts/FigmaTokenContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAE5D,eAAO,MAAM,iBAAiB,4DAA8D,CAAC"}
+{"version":3,"file":"FigmaTokenContext.d.ts","sourceRoot":"","sources":["../../src/contexts/FigmaTokenContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAE3D,eAAO,MAAM,iBAAiB,4DAElB,CAAA"}

package/dist/contexts/FigmaVarsProvider.d.ts

@@ -7,6 +7,8 @@ import { FigmaVarsProviderProps } from '../types/contexts';
  *
  * This is the central source of truth for Figma authentication and file context within the app.
  *
+ * Fallback JSON files are parsed once during provider initialization to avoid repeated parsing and provide early validation.
+ *
  * @example
  * ```tsx
  * import { FigmaVarsProvider } from '@figma-vars/hooks/contexts';
@@ -22,5 +24,5 @@ import { FigmaVarsProviderProps } from '../types/contexts';
  *
  * @public
  */
-export declare const FigmaVarsProvider: ({ children, token, fileKey, fallbackFile, }: FigmaVarsProviderProps) => import("react/jsx-runtime").JSX.Element;
+export declare const FigmaVarsProvider: ({ children, token, fileKey, fallbackFile, swrConfig, }: FigmaVarsProviderProps) => import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=FigmaVarsProvider.d.ts.map

package/dist/contexts/FigmaVarsProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FigmaVarsProvider.d.ts","sourceRoot":"","sources":["../../src/contexts/FigmaVarsProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAyB,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAGpF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,iBAAiB,GAAI,6CAK/B,sBAAsB,4CAUxB,CAAC"}
+{"version":3,"file":"FigmaVarsProvider.d.ts","sourceRoot":"","sources":["../../src/contexts/FigmaVarsProvider.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,sBAAsB,EACvB,MAAM,gBAAgB,CAAA;AAIvB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,iBAAiB,GAAI,wDAM/B,sBAAsB,4CAqFxB,CAAA"}

package/dist/contexts/index.d.ts

@@ -18,7 +18,7 @@
  * }
  * ```
  */
-export { FigmaVarsProvider, } from './FigmaVarsProvider';
+export { FigmaVarsProvider } from './FigmaVarsProvider';
 export { useFigmaTokenContext } from './useFigmaTokenContext';
 export { FigmaTokenContext } from './FigmaTokenContext';
 //# sourceMappingURL=index.d.ts.map

package/dist/contexts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contexts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contexts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/contexts/useFigmaTokenContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFigmaTokenContext.d.ts","sourceRoot":"","sources":["../../src/contexts/useFigmaTokenContext.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAE5D,eAAO,MAAM,oBAAoB,QAAO,qBAMvC,CAAC"}
+{"version":3,"file":"useFigmaTokenContext.d.ts","sourceRoot":"","sources":["../../src/contexts/useFigmaTokenContext.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAE3D,eAAO,MAAM,oBAAoB,QAAO,qBAQvC,CAAA"}

package/dist/core/index.d.cts

@@ -0,0 +1,8 @@
+import { fetcher } from '../api/fetcher.js';
+import { mutator } from '../api/mutator.js';
+import { filterVariables } from '../utils/filterVariables.js';
+export { fetcher, mutator, filterVariables };
+export * from '../constants/index.js';
+export type * from '../types/figma.js';
+export type * from '../types/mutations.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts

@@ -0,0 +1,8 @@
+import { fetcher } from '../api/fetcher.js';
+import { mutator } from '../api/mutator.js';
+import { filterVariables } from '../utils/filterVariables.js';
+export { fetcher, mutator, filterVariables };
+export * from '../constants/index.js';
+export type * from '../types/figma.js';
+export type * from '../types/mutations.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAE7D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,CAAA;AAC5C,cAAc,uBAAuB,CAAA;AACrC,mBAAmB,mBAAmB,CAAA;AACtC,mBAAmB,uBAAuB,CAAA"}

package/dist/core.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const _=require("./index-5ZyKWuYv.cjs");exports.CONTENT_TYPE_JSON=_.CONTENT_TYPE_JSON;exports.ERROR_MSG_BULK_UPDATE_FAILED=_.ERROR_MSG_BULK_UPDATE_FAILED;exports.ERROR_MSG_CREATE_VARIABLE_FAILED=_.ERROR_MSG_CREATE_VARIABLE_FAILED;exports.ERROR_MSG_DELETE_VARIABLE_FAILED=_.ERROR_MSG_DELETE_VARIABLE_FAILED;exports.ERROR_MSG_FETCH_FIGMA_DATA_FAILED=_.ERROR_MSG_FETCH_FIGMA_DATA_FAILED;exports.ERROR_MSG_TOKEN_FILE_KEY_REQUIRED=_.ERROR_MSG_TOKEN_FILE_KEY_REQUIRED;exports.ERROR_MSG_TOKEN_REQUIRED=_.ERROR_MSG_TOKEN_REQUIRED;exports.ERROR_MSG_UPDATE_VARIABLE_FAILED=_.ERROR_MSG_UPDATE_VARIABLE_FAILED;exports.FIGMA_API_BASE_URL=_.FIGMA_API_BASE_URL;exports.FIGMA_FILES_ENDPOINT=_.FIGMA_FILES_ENDPOINT;exports.FIGMA_FILE_VARIABLES_PATH=_.FIGMA_FILE_VARIABLES_PATH;exports.FIGMA_LOCAL_VARIABLES_ENDPOINT=_.FIGMA_LOCAL_VARIABLES_ENDPOINT;exports.FIGMA_PUBLISHED_VARIABLES_PATH=_.FIGMA_PUBLISHED_VARIABLES_PATH;exports.FIGMA_TOKEN_HEADER=_.FIGMA_TOKEN_HEADER;exports.fetcher=_.fetcher;exports.filterVariables=_.filterVariables;exports.mutator=_.mutator;

package/dist/core.d.cts

@@ -0,0 +1,2 @@
+export * from './core/index'
+export {}

package/dist/core.d.ts

@@ -0,0 +1,2 @@
+export * from './core/index'
+export {}

package/dist/core.mjs

@@ -0,0 +1,20 @@
+import { C as A, j as R, k as I, l as a, o as L, a as s, E as F, n as T, d as D, e as O, F as G, h as M, g as S, i as N, f as B, c as P, m as U } from "./index-ClHLYVvu.js";
+export {
+  A as CONTENT_TYPE_JSON,
+  R as ERROR_MSG_BULK_UPDATE_FAILED,
+  I as ERROR_MSG_CREATE_VARIABLE_FAILED,
+  a as ERROR_MSG_DELETE_VARIABLE_FAILED,
+  L as ERROR_MSG_FETCH_FIGMA_DATA_FAILED,
+  s as ERROR_MSG_TOKEN_FILE_KEY_REQUIRED,
+  F as ERROR_MSG_TOKEN_REQUIRED,
+  T as ERROR_MSG_UPDATE_VARIABLE_FAILED,
+  D as FIGMA_API_BASE_URL,
+  O as FIGMA_FILES_ENDPOINT,
+  G as FIGMA_FILE_VARIABLES_PATH,
+  M as FIGMA_LOCAL_VARIABLES_ENDPOINT,
+  S as FIGMA_PUBLISHED_VARIABLES_PATH,
+  N as FIGMA_TOKEN_HEADER,
+  B as fetcher,
+  P as filterVariables,
+  U as mutator
+};

package/dist/hooks/index.d.ts

@@ -141,4 +141,68 @@ export { useDeleteVariable } from './useDeleteVariable';
  * @public
  */
 export { useBulkUpdateVariables } from './useBulkUpdateVariables';
+export { useInvalidateVariables } from './useInvalidateVariables';
+/**
+ * React hook to fetch published Figma Variables from a file.
+ *
+ * @remarks
+ * Fetches variables that have been published to a library. Published variables
+ * are shared across files and represent the source of truth for design tokens.
+ *
+ * @see {@link https://www.figma.com/developers/api#variables | Figma Variables API}
+ *
+ * @example
+ * ```tsx
+ * import { usePublishedVariables } from '@figma-vars/hooks';
+ * const { data, isLoading } = usePublishedVariables();
+ * ```
+ *
+ * @public
+ */
+export { usePublishedVariables } from './usePublishedVariables';
+/**
+ * React hook to select a single variable by ID from loaded Figma variables data.
+ *
+ * @remarks
+ * Returns the variable with the specified ID, or undefined if not found.
+ *
+ * @example
+ * ```tsx
+ * import { useVariableById } from '@figma-vars/hooks';
+ * const variable = useVariableById('VariableID:123:456');
+ * ```
+ *
+ * @public
+ */
+export { useVariableById } from './useVariableById';
+/**
+ * React hook to select a single variable collection by ID from loaded Figma variables data.
+ *
+ * @remarks
+ * Returns the collection with the specified ID, or undefined if not found.
+ *
+ * @example
+ * ```tsx
+ * import { useCollectionById } from '@figma-vars/hooks';
+ * const collection = useCollectionById('VariableCollectionId:123:456');
+ * ```
+ *
+ * @public
+ */
+export { useCollectionById } from './useCollectionById';
+/**
+ * React hook to select modes for a specific variable collection.
+ *
+ * @remarks
+ * Returns an array of modes belonging to the specified collection.
+ *
+ * @example
+ * ```tsx
+ * import { useModesByCollection } from '@figma-vars/hooks';
+ * const modes = useModesByCollection('VariableCollectionId:123:456');
+ * ```
+ *
+ * @public
+ */
+export { useModesByCollection } from './useModesByCollection';
 //# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AACtE;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC/D;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAA;AACrE;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAC9D;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAA;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAA;AACrE;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAA;AACnE;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA"}

package/dist/hooks/useBulkUpdateVariables.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useBulkUpdateVariables.d.ts","sourceRoot":"","sources":["../../src/hooks/useBulkUpdateVariables.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAOzD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,sBAAsB,4EAclC,CAAC"}
+{"version":3,"file":"useBulkUpdateVariables.d.ts","sourceRoot":"","sources":["../../src/hooks/useBulkUpdateVariables.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAQxD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,sBAAsB,4EAiBlC,CAAA"}

package/dist/hooks/useCollectionById.d.ts

@@ -0,0 +1,31 @@
+import { FigmaCollection } from 'types';
+/**
+ * React hook that selects a single variable collection by ID from loaded Figma variables data.
+ *
+ * @remarks
+ * Returns the collection with the specified ID, or `undefined` if not found.
+ * Useful for accessing a specific collection without manually mapping through all collections.
+ *
+ * @param collectionId - The ID of the collection to retrieve.
+ * @returns The collection object, or `undefined` if not found.
+ *
+ * @example
+ * ```tsx
+ * import { useCollectionById } from '@figma-vars/hooks';
+ *
+ * function CollectionDetails({ collectionId }: { collectionId: string }) {
+ *   const collection = useCollectionById(collectionId);
+ *
+ *   if (!collection) return <div>Collection not found</div>;
+ *
+ *   return <div>
+ *     <h2>{collection.name}</h2>
+ *     <p>Variables: {collection.variableIds.length}</p>
+ *   </div>;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare const useCollectionById: (collectionId: string) => FigmaCollection | undefined;
+//# sourceMappingURL=useCollectionById.d.ts.map

package/dist/hooks/useCollectionById.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCollectionById.d.ts","sourceRoot":"","sources":["../../src/hooks/useCollectionById.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,OAAO,CAAA;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,iBAAiB,GAC5B,cAAc,MAAM,KACnB,eAAe,GAAG,SAMpB,CAAA"}

package/dist/hooks/useCreateVariable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCreateVariable.d.ts","sourceRoot":"","sources":["../../src/hooks/useCreateVariable.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAO7D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,iBAAiB,gFAc7B,CAAC"}
+{"version":3,"file":"useCreateVariable.d.ts","sourceRoot":"","sources":["../../src/hooks/useCreateVariable.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AAQ5D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,iBAAiB,gFAmB7B,CAAA"}

package/dist/hooks/useDeleteVariable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useDeleteVariable.d.ts","sourceRoot":"","sources":["../../src/hooks/useDeleteVariable.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,iBAAiB,oDAc7B,CAAC"}
+{"version":3,"file":"useDeleteVariable.d.ts","sourceRoot":"","sources":["../../src/hooks/useDeleteVariable.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,iBAAiB,oDAmB7B,CAAA"}

package/dist/hooks/useFigmaToken.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFigmaToken.d.ts","sourceRoot":"","sources":["../../src/hooks/useFigmaToken.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,QAAA,MAAM,aAAa,QAAO,MAAM,GAAG,IAGlC,CAAC;AAEF,eAAe,aAAa,CAAC"}
+{"version":3,"file":"useFigmaToken.d.ts","sourceRoot":"","sources":["../../src/hooks/useFigmaToken.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,QAAA,MAAM,aAAa,QAAO,MAAM,GAAG,IAGlC,CAAA;AAED,eAAe,aAAa,CAAA"}

package/dist/hooks/useInvalidateVariables.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Hook that provides cache invalidation utilities for Figma variables.
+ *
+ * @remarks
+ * Returns functions to invalidate and revalidate SWR cache for variables hooks.
+ * Use this after mutations to ensure fresh data is fetched.
+ *
+ * Supports both live API usage (with token and fileKey) and fallback-only usage
+ * (with fallbackFile but no fileKey).
+ *
+ * @returns Object with `invalidate` and `revalidate` functions.
+ *
+ * @example
+ * ```tsx
+ * import { useInvalidateVariables, useUpdateVariable } from '@figma-vars/hooks';
+ *
+ * function UpdateButton() {
+ *   const { mutate } = useUpdateVariable();
+ *   const { invalidate } = useInvalidateVariables();
+ *
+ *   const handleUpdate = async () => {
+ *     await mutate({ variableId: 'id', payload: { name: 'New Name' } });
+ *     invalidate(); // Refetch all variable queries
+ *   };
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare const useInvalidateVariables: () => {
+    invalidate: () => void;
+    revalidate: () => void;
+};
+//# sourceMappingURL=useInvalidateVariables.d.ts.map

package/dist/hooks/useInvalidateVariables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useInvalidateVariables.d.ts","sourceRoot":"","sources":["../../src/hooks/useInvalidateVariables.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,sBAAsB;;;CAoDlC,CAAA"}

package/dist/hooks/useModesByCollection.d.ts

@@ -0,0 +1,34 @@
+import { VariableMode } from 'types';
+/**
+ * React hook that selects modes for a specific variable collection.
+ *
+ * @remarks
+ * Returns an array of modes belonging to the specified collection, or an empty array if not found.
+ * Useful for filtering modes by collection without manually accessing modesByCollectionId.
+ *
+ * @param collectionId - The ID of the collection to get modes for.
+ * @returns An array of VariableMode objects for the collection, or an empty array if not found.
+ *
+ * @example
+ * ```tsx
+ * import { useModesByCollection } from '@figma-vars/hooks';
+ *
+ * function CollectionModes({ collectionId }: { collectionId: string }) {
+ *   const modes = useModesByCollection(collectionId);
+ *
+ *   if (!modes.length) return <div>No modes found</div>;
+ *
+ *   return (
+ *     <ul>
+ *       {modes.map(mode => (
+ *         <li key={mode.modeId}>{mode.name}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare const useModesByCollection: (collectionId: string) => VariableMode[];
+//# sourceMappingURL=useModesByCollection.d.ts.map

package/dist/hooks/useModesByCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useModesByCollection.d.ts","sourceRoot":"","sources":["../../src/hooks/useModesByCollection.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,oBAAoB,GAAI,cAAc,MAAM,KAAG,YAAY,EAMvE,CAAA"}

package/dist/hooks/usePublishedVariables.d.ts

@@ -0,0 +1,42 @@
+import { PublishedVariablesResponse } from '../types/figma';
+/**
+ * Hook to fetch published Figma Variables from a file.
+ *
+ * @remarks
+ * This hook fetches variables that have been published to a library in Figma.
+ * Published variables are shared across files and represent the "source of truth"
+ * for design tokens in a design system. Use this hook when you need to access
+ * variables that are consumed from a library, rather than local file variables.
+ *
+ * **When to use:**
+ * - Fetching design tokens from a published library
+ * - Building design system dashboards that track published tokens
+ * - Monitoring changes to shared variables across a design system
+ * - Validating consistency between published and local variables
+ *
+ * **Rate Limiting:**
+ * The Figma API has rate limits. Published variables are typically more stable
+ * than local variables, so they can be cached longer. SWR handles caching and
+ * revalidation automatically, but be mindful of frequent refetches in production.
+ *
+ * @returns SWR response object with `data`, `error`, `isLoading`, and `isValidating`.
+ *
+ * @public
+ *
+ * @example
+ * ```tsx
+ * import { usePublishedVariables } from '@figma-vars/hooks';
+ *
+ * function LibraryTokens() {
+ *   const { data, isLoading, error } = usePublishedVariables();
+ *
+ *   if (isLoading) return <div>Loading published variables...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   const variables = Object.values(data?.meta.variables ?? {});
+ *   return <ul>{variables.map(v => <li key={v.id}>{v.name}</li>)}</ul>;
+ * }
+ * ```
+ */
+export declare const usePublishedVariables: () => import('swr').SWRResponse<PublishedVariablesResponse, any, import('swr').SWRConfiguration<PublishedVariablesResponse, any, import('swr').BareFetcher<PublishedVariablesResponse>> | undefined>;
+//# sourceMappingURL=usePublishedVariables.d.ts.map

package/dist/hooks/usePublishedVariables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePublishedVariables.d.ts","sourceRoot":"","sources":["../../src/hooks/usePublishedVariables.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAA;AAI7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,qBAAqB,sMA+CjC,CAAA"}

package/dist/hooks/useUpdateVariable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useUpdateVariable.d.ts","sourceRoot":"","sources":["../../src/hooks/useUpdateVariable.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAI7D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,iBAAiB;gBAGoB,MAAM;aAAW,qBAAqB;EAavF,CAAC"}
+{"version":3,"file":"useUpdateVariable.d.ts","sourceRoot":"","sources":["../../src/hooks/useUpdateVariable.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AAQ5D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,iBAAiB;gBAOZ,MAAM;aACT,qBAAqB;EAyBnC,CAAA"}

package/dist/hooks/useVariableById.d.ts

@@ -0,0 +1,31 @@
+import { FigmaVariable } from 'types';
+/**
+ * React hook that selects a single variable by ID from loaded Figma variables data.
+ *
+ * @remarks
+ * Returns the variable with the specified ID, or `undefined` if not found.
+ * Useful for accessing a specific variable without manually mapping through all variables.
+ *
+ * @param variableId - The ID of the variable to retrieve.
+ * @returns The variable object, or `undefined` if not found.
+ *
+ * @example
+ * ```tsx
+ * import { useVariableById } from '@figma-vars/hooks';
+ *
+ * function VariableDetails({ variableId }: { variableId: string }) {
+ *   const variable = useVariableById(variableId);
+ *
+ *   if (!variable) return <div>Variable not found</div>;
+ *
+ *   return <div>
+ *     <h2>{variable.name}</h2>
+ *     <p>Type: {variable.resolvedType}</p>
+ *   </div>;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare const useVariableById: (variableId: string) => FigmaVariable | undefined;
+//# sourceMappingURL=useVariableById.d.ts.map

package/dist/hooks/useVariableById.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVariableById.d.ts","sourceRoot":"","sources":["../../src/hooks/useVariableById.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,eAAe,GAC1B,YAAY,MAAM,KACjB,aAAa,GAAG,SASlB,CAAA"}

package/dist/hooks/useVariableCollections.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useVariableCollections.d.ts","sourceRoot":"","sources":["../../src/hooks/useVariableCollections.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,sBAAsB;;;CAiBlC,CAAC"}
+{"version":3,"file":"useVariableCollections.d.ts","sourceRoot":"","sources":["../../src/hooks/useVariableCollections.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,OAAO,CAAA;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,sBAAsB;;;CAiBlC,CAAA"}

package/dist/hooks/useVariableModes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useVariableModes.d.ts","sourceRoot":"","sources":["../../src/hooks/useVariableModes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,gBAAgB,QAAO,sBAwBnC,CAAC"}
+{"version":3,"file":"useVariableModes.d.ts","sourceRoot":"","sources":["../../src/hooks/useVariableModes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,gBAAgB,QAAO,sBA0BnC,CAAA"}

package/dist/hooks/useVariables.d.ts

@@ -4,7 +4,9 @@ import { LocalVariablesResponse } from '../types/figma';
  *
  * @remarks
  * This hook uses SWR for caching and revalidation. It fetches the variables for the
- * file key provided via the FigmaVarsProvider context.
+ * file key provided via the FigmaVarsProvider context. If a fallbackFile is provided,
+ * it will use that instead of making an API request, which is useful for users without
+ * Figma Enterprise accounts or for offline development.
  *
  * @returns SWR response object with `data`, `error`, `isLoading`, and `isValidating`.
  *