@figma-vars/hooks 1.5.1 → 2.0.0-beta.2

package/README.md

@@ -26,6 +26,8 @@ Built for the modern web, this library provides a suite of hooks to fetch, manag
 - **✍️ Ergonomic Mutations**: A `useMutation`-style API for creating, updating, and deleting variables, providing clear loading and error states.
 - **🔒 TypeScript-first**: Strictly typed for an ergonomic and safe developer experience. Get autocompletion for all API responses.
 - **📖 Storybook & Next.js Ready**: Perfect for building live design token dashboards or style guides.
+- **🔄 Local JSON Support**: Use local JSON files exported from Figma Dev Mode plugins when you don't have a Figma Enterprise account, enabling offline development and static deployments.
+- **🚧 Style Dictionary Integration**: Coming soon in future beta releases - seamless integration with Amazon's Style Dictionary for multi-platform design token distribution.
 
 ---
 
@@ -162,6 +164,61 @@ function CreateVariableForm({ collectionId }: { collectionId: string }) {
 }
 ```
 
+### Using Local JSON Files (No Enterprise Account Required)
+
+If you don't have a Figma Enterprise account (required for the Variables API), you can still use this library with local JSON files exported from Figma Dev Mode plugins. This is perfect for:
+
+- **Offline Development**: Work on your design system without an internet connection
+- **Static Deployments**: Deploy design token dashboards to static hosting
+- **CI/CD Pipelines**: Use exported JSON files in automated workflows
+- **Team Collaboration**: Share design tokens without API access
+
+#### Getting Your JSON File
+
+We recommend using the [Variables Exporter for Dev Mode](https://www.figma.com/community/plugin/1491572182178544621) plugin:
+
+1. Install the plugin in Figma
+2. Open your Figma file in Dev Mode
+3. Run the plugin and export your variables as JSON
+4. Save the JSON file to your project (e.g., `src/assets/figma-variables.json`)
+
+This plugin exports the exact same format that the Figma Variables API returns, ensuring perfect compatibility with this library.
+
+#### Using the Fallback File
+
+```tsx
+// src/main.tsx or App.tsx
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { FigmaVarsProvider } from '@figma-vars/hooks'
+import App from './App'
+import variablesData from './assets/figma-variables.json'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <FigmaVarsProvider
+      token={null} // No token needed when using fallbackFile
+      fileKey="your-figma-file-key"
+      fallbackFile={variablesData}>
+      <App />
+    </FigmaVarsProvider>
+  </React.StrictMode>
+)
+```
+
+You can also pass the JSON as a string if you prefer:
+
+```tsx
+import variablesJson from './assets/figma-variables.json?raw'
+
+<FigmaVarsProvider
+  token={null}
+  fileKey="your-figma-file-key"
+  fallbackFile={variablesJson}>
+  <App />
+</FigmaVarsProvider>
+```
+
 ### Figma PAT Security
 
 When using the Figma API, it's essential to keep your Personal Access Token (PAT) secure. Here are some best practices:
@@ -231,11 +288,19 @@ function ErrorHandling() {
 
 ### Core Hooks
 
-- `useVariables()`: Fetches all local variables for the file key provided to the `FigmaVarsProvider`. Returns a SWR hook state with `data`, `isLoading`, and `error` properties. The actual Figma response is in `data.data`.
+- `useVariables()`: Fetches all local variables for the file key provided to the `FigmaVarsProvider`. Returns a SWR hook state with `data`, `isLoading`, and `error` properties. The actual Figma response is in `data.data`. When `fallbackFile` is provided, it uses the local JSON data instead of making an API request.
 - `useVariableCollections()`: A convenience hook that returns just the variable collections from the main `useVariables` data.
 - `useVariableModes()`: A convenience hook that returns just the variable modes from the main `useVariables` data.
 - `useFigmaToken()`: A simple hook to access the token and file key from the context.
 
+### Provider Props
+
+The `FigmaVarsProvider` accepts the following props:
+
+- `token`: Figma Personal Access Token (PAT) for API authentication. Can be `null` when using `fallbackFile`.
+- `fileKey`: Figma file key for the target file. Required for API requests but can be any string when using `fallbackFile`.
+- `fallbackFile`: Optional local JSON file (as object or string) to use instead of API requests. Perfect for users without Figma Enterprise accounts.
+
 ### Mutation Hooks
 
 All mutation hooks return an object with the following shape: `{ mutate, data, isLoading, error }`.

package/dist/api/fetcher.d.ts

@@ -25,4 +25,5 @@
  * }
  * ```
  */
-export declare function fetcher(url: string, token: string): Promise<any>;
+export declare function fetcher<TResponse = unknown>(url: string, token: string): Promise<TResponse>;
+//# sourceMappingURL=fetcher.d.ts.map

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

@@ -0,0 +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"}

package/dist/api/index.d.ts

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

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

@@ -0,0 +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"}

package/dist/api/mutator.d.ts

@@ -30,4 +30,5 @@ import { VariableAction } from '../types/mutations';
  * }
  * ```
  */
-export declare function mutator(url: string, token: string, action: VariableAction, body?: any): Promise<any>;
+export declare function mutator<TResponse = unknown, TBody extends Record<string, unknown> = Record<string, unknown>>(url: string, token: string, action: VariableAction, body?: TBody): Promise<TResponse>;
+//# sourceMappingURL=mutator.d.ts.map

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

@@ -0,0 +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"}

package/dist/constants/index.d.ts

@@ -87,3 +87,4 @@ export declare const ERROR_MSG_UPDATE_VARIABLE_FAILED = "Failed to update Figma
  * Error message when fetching data from the Figma API fails.
  */
 export declare const ERROR_MSG_FETCH_FIGMA_DATA_FAILED = "An error occurred while fetching data from the Figma API.";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/dist/contexts/FigmaTokenContext.d.ts

@@ -0,0 +1,3 @@
+import { FigmaTokenContextType } from '../types/contexts';
+export declare const FigmaTokenContext: import('react').Context<FigmaTokenContextType | undefined>;
+//# sourceMappingURL=FigmaTokenContext.d.ts.map

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

@@ -0,0 +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"}

package/dist/contexts/FigmaVarsProvider.d.ts

@@ -1,4 +1,4 @@
-import { FigmaTokenContextType, FigmaVarsProviderProps } from '../types/contexts';
+import { FigmaVarsProviderProps } from '../types/contexts';
 /**
  * React context provider that supplies the Figma Personal Access Token and file key to all descendant components.
  *
@@ -22,35 +22,5 @@ import { FigmaTokenContextType, FigmaVarsProviderProps } from '../types/contexts
  *
  * @public
  */
-export declare const FigmaVarsProvider: ({ children, token, fileKey, }: FigmaVarsProviderProps) => import("react/jsx-runtime").JSX.Element;
-/**
- * React hook to access the current Figma Personal Access Token and file key from context.
- *
- * @remarks
- * Retrieves the token and file key provided by the nearest `FigmaVarsProvider`.
- * Throws a descriptive error if used outside of the provider to prevent silent failures.
- *
- * Use this hook in any component or hook that requires authenticated access to the Figma Variables API scoped to a file.
- *
- * @returns The current FigmaTokenContextType containing `{ token, fileKey }`.
- *
- * @throws Throws if called outside of a `FigmaVarsProvider` context.
- *
- * @example
- * ```tsx
- * import { useFigmaTokenContext } from '@figma-vars/hooks/contexts';
- *
- * function DebugToken() {
- *   const { token, fileKey } = useFigmaTokenContext();
- *   return (
- *     <div>
- *       <p>Token: {token?.slice(0, 6)}... (hidden for security)</p>
- *       <p>File Key: {fileKey}</p>
- *     </div>
- *   );
- * }
- * ```
- *
- * @public
- */
-export declare const useFigmaTokenContext: () => FigmaTokenContextType;
+export declare const FigmaVarsProvider: ({ children, token, fileKey, fallbackFile, }: FigmaVarsProviderProps) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=FigmaVarsProvider.d.ts.map

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

@@ -0,0 +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"}

package/dist/contexts/index.d.ts

@@ -18,4 +18,7 @@
  * }
  * ```
  */
-export { FigmaVarsProvider, useFigmaTokenContext, } 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

@@ -0,0 +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"}

package/dist/contexts/useFigmaTokenContext.d.ts

@@ -0,0 +1,3 @@
+import { FigmaTokenContextType } from '../types/contexts';
+export declare const useFigmaTokenContext: () => FigmaTokenContextType;
+//# sourceMappingURL=useFigmaTokenContext.d.ts.map

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

@@ -0,0 +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"}

package/dist/hooks/index.d.ts

@@ -141,3 +141,4 @@ export { useDeleteVariable } from './useDeleteVariable';
  * @public
  */
 export { useBulkUpdateVariables } from './useBulkUpdateVariables';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/dist/hooks/useBulkUpdateVariables.d.ts

@@ -3,44 +3,29 @@ import { BulkUpdatePayload } from '../types/mutations';
  * React hook that performs a bulk update of multiple Figma variables in a single request via the Figma Variables API.
  *
  * @remarks
- * Returns a mutation object with status flags and error info.
- * Call `mutate(payload)` with a `BulkUpdatePayload` object to trigger the update—`payload` must include:
- * - `variableIds`: array of Figma variable IDs to update
- * - `variableCollectionId`: the collection context for the update
- * - `updates`: an object mapping variable IDs to their updated values or properties
- *
- * The hook throws if the Figma Personal Access Token (PAT) is missing from context.
- * Use for advanced workflows requiring atomic, multi-variable updates.
- *
- * @see {@link https://www.figma.com/developers/api#variables | Figma Variables API}
+ * This hook is designed to perform a batch operation for creating, updating, and deleting variables, collections, and modes.
+ * It provides an ergonomic API with `mutate` and loading/error state for easy integration.
  *
  * @example
  * ```tsx
  * import { useBulkUpdateVariables } from '@figma-vars/hooks';
  *
- * function BulkUpdateComponent() {
- *   const { mutate, isLoading, isSuccess, error } = useBulkUpdateVariables();
+ * function BulkUpdateButton() {
+ *   const { mutate, isLoading, error } = useBulkUpdateVariables();
  *
  *   const handleBulkUpdate = () => {
  *     mutate({
- *       variableIds: ['VariableID:123:456', 'VariableID:123:457'],
- *       variableCollectionId: 'VariableCollectionId:123:456',
- *       updates: {
- *         'VariableID:123:456': { name: 'Primary Color Updated' },
- *         'VariableID:123:457': { name: 'Secondary Color Updated' }
- *       }
+ *       variables: [{ action: 'UPDATE', id: 'VariableId:123', name: 'new-name' }],
  *     });
  *   };
  *
- *   if (!mutate) return <div>Not authorized. Figma token missing.</div>;
- *   if (isLoading) return <div>Updating variables…</div>;
- *   if (error) return <div style={{ color: 'red' }}>Error: {error.message}</div>;
- *   if (isSuccess) return <div>Variables updated successfully!</div>;
- *
- *   return <button onClick={handleBulkUpdate}>Update All Variables</button>;
+ *   if (isLoading) return <div>Updating...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   return <button onClick={handleBulkUpdate}>Bulk Update</button>;
  * }
  * ```
  *
  * @public
  */
-export declare const useBulkUpdateVariables: () => import('../types/mutations').MutationResult<any, BulkUpdatePayload>;
+export declare const useBulkUpdateVariables: () => import('../types/mutations').MutationResult<unknown, BulkUpdatePayload>;
+//# sourceMappingURL=useBulkUpdateVariables.d.ts.map

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

@@ -0,0 +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"}

package/dist/hooks/useCreateVariable.d.ts

@@ -3,43 +3,26 @@ import { CreateVariablePayload } from '../types/mutations';
  * React hook that creates a new Figma variable in the current file using the Figma Variables API.
  *
  * @remarks
- * Returns a mutation object with status flags and error info. To trigger creation, call `mutate(payload)` with a `CreateVariablePayload` object containing:
- * - `name`: the variable name
- * - `variableCollectionId`: target collection ID
- * - `resolvedType`: variable type
- * - `valuesByMode`: values for one or more modes
- *
- * Throws if the Figma Personal Access Token (PAT) is missing from context.
- * Use for advanced workflows, automated variable management, or custom UI tooling.
- *
- * @see {@link https://www.figma.com/developers/api#variables | Figma Variables API}
+ * The hook returns a `mutate` function to trigger the creation along with state flags and data.
  *
  * @example
  * ```tsx
  * import { useCreateVariable } from '@figma-vars/hooks';
  *
- * function CreateVariableComponent() {
- *   const { mutate, isLoading, isSuccess, error } = useCreateVariable();
+ * function CreateVariableButton() {
+ *   const { mutate, isLoading, error } = useCreateVariable();
  *
  *   const handleCreate = () => {
- *     mutate({
- *       name: 'Primary Color',
- *       variableCollectionId: 'VariableCollectionId:123:456',
- *       resolvedType: 'COLOR',
- *       valuesByMode: {
- *         '42:0': { r: 0.2, g: 0.4, b: 0.8, a: 1 }
- *       }
- *     });
+ *     mutate({ name: 'new-variable', variableCollectionId: 'VariableCollectionId:1:1', resolvedType: 'COLOR' });
  *   };
  *
- *   if (isLoading) return <div>Creating variable…</div>;
- *   if (error) return <div style={{ color: 'red' }}>Error: {error.message}</div>;
- *   if (isSuccess) return <div>Variable created successfully!</div>;
- *
+ *   if (isLoading) return <div>Creating...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
  *   return <button onClick={handleCreate}>Create Variable</button>;
  * }
  * ```
  *
  * @public
  */
-export declare const useCreateVariable: () => import('../types/mutations').MutationResult<any, CreateVariablePayload>;
+export declare const useCreateVariable: () => import('../types/mutations').MutationResult<unknown, CreateVariablePayload>;
+//# sourceMappingURL=useCreateVariable.d.ts.map

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

@@ -0,0 +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"}

package/dist/hooks/useDeleteVariable.d.ts

@@ -2,32 +2,24 @@
  * React hook that deletes a Figma variable by ID using the Figma Variables API.
  *
  * @remarks
- * Returns a mutation object with status flags and error info. To trigger deletion, call `mutate(variableId)` with the variable's ID as a string.
- * Throws if the Figma Personal Access Token (PAT) is missing from context.
- * Use this for advanced workflows, admin tooling, or custom variable management UIs.
- *
- * @see {@link https://www.figma.com/developers/api#variables | Figma Variables API}
+ * This hook provides a `mutate` function to trigger the deletion and exposes loading and error states.
  *
  * @example
  * ```tsx
  * import { useDeleteVariable } from '@figma-vars/hooks';
  *
- * function DeleteVariableButton({ variableId }: { variableId: string }) {
- *   const { mutate, isLoading, isSuccess, error } = useDeleteVariable();
- *
- *   const handleDelete = () => {
- *     mutate(variableId); // variableId must be a string
- *   };
+ * function DeleteVariableButton({ id }: { id: string }) {
+ *   const { mutate, isLoading, error } = useDeleteVariable();
  *
- *   if (!mutate) return <div>Not authorized. Figma token missing.</div>;
- *   if (isLoading) return <div>Deleting variable…</div>;
- *   if (error) return <div style={{ color: 'red' }}>Error: {error.message}</div>;
- *   if (isSuccess) return <div>Variable deleted successfully!</div>;
+ *   const onDelete = () => mutate(id);
  *
- *   return <button onClick={handleDelete}>Delete Variable</button>;
+ *   if (isLoading) return <div>Deleting...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   return <button onClick={onDelete}>Delete Variable</button>;
  * }
  * ```
  *
  * @public
  */
-export declare const useDeleteVariable: () => import('..').MutationResult<any, string>;
+export declare const useDeleteVariable: () => import('..').MutationResult<unknown, string>;
+//# sourceMappingURL=useDeleteVariable.d.ts.map

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

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

package/dist/hooks/useFigmaToken.d.ts

@@ -19,3 +19,4 @@
  */
 declare const useFigmaToken: () => string | null;
 export default useFigmaToken;
+//# sourceMappingURL=useFigmaToken.d.ts.map

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

@@ -0,0 +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"}

package/dist/hooks/useMutation.d.ts

@@ -1,53 +1,2 @@
-import { MutationState, MutationResult } from '../types/mutations';
-type MutationStatus = 'idle' | 'loading' | 'success' | 'error';
-/**
- * Internal reducer to manage async mutation state for all mutation hooks.
- *
- * @remarks
- * Handles mutation status transitions (`loading`, `success`, `error`) and enforces consistent error/data handling across the library.
- * Used by {@link useMutation} and not intended for direct use in external code.
- *
- * @typeParam TData - The type of data returned by the mutation.
- *
- * @example
- * ```ts
- * import { mutationReducer } from '@figma-vars/hooks';
- * const [state, dispatch] = useReducer(mutationReducer, initialState);
- * // Internal pattern for mutation state management
- * ```
- *
- * @internal
- */
-export declare function mutationReducer<TData>(state: MutationState<TData>, action: {
-    type: MutationStatus;
-    payload?: TData | Error;
-}): MutationState<TData>;
-/**
- * Internal React hook for async mutation state, status flags, and mutation trigger.
- *
- * @remarks
- * Returns a mutation object with status, error, and result data. Preferred pattern: use higher-level hooks (e.g., `useCreateVariable`, `useUpdateVariable`) rather than using this directly in production code.
- * The provided `mutationFn` must be an async function that performs the actual mutation (API call, etc). See example for pattern.
- *
- * @typeParam TData - Type returned by the mutation.
- * @typeParam TPayload - Payload accepted by the mutation function.
- * @param mutationFn - Async function performing the mutation logic.
- * @returns Mutation state, status flags, and a `mutate(payload)` trigger function.
- *
- * @example
- * ```ts
- * import { useMutation } from '@figma-vars/hooks';
- *
- * // Example: use for custom async logic
- * const { mutate, isLoading, isSuccess, error } = useMutation(async (payload: MyPayload) => {
- *   // Your async mutation logic here (e.g., API call)
- *   return result;
- * });
- *
- * // Call mutate(payload) to trigger the mutation.
- * ```
- *
- * @internal
- */
-export declare const useMutation: <TData, TPayload>(mutationFn: (payload: TPayload) => Promise<TData>) => MutationResult<TData, TPayload>;
 export {};
+//# sourceMappingURL=useMutation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useMutation.d.ts","sourceRoot":"","sources":["../../src/hooks/useMutation.ts"],"names":[],"mappings":""}

package/dist/hooks/useUpdateVariable.d.ts

@@ -1,40 +1,29 @@
-import { UpdateVariableArgs } from '../types/hooks';
+import { UpdateVariablePayload } from '../types/mutations';
 /**
- * React hook that updates a Figma variable by its ID via the Figma Variables API.
+ * React hook that updates an existing Figma variable by ID using the Figma Variables API.
  *
  * @remarks
- * Returns a mutation object with status flags, error info, and a trigger function. Call `mutate({ variableId, payload })` to update a variable—provide the target variable's ID and the update payload.
- * Throws if the Figma Personal Access Token (PAT) is missing from context.
- * Use for advanced UI tooling or bulk edit workflows.
- *
- * @see {@link https://www.figma.com/developers/api#variables | Figma Variables API}
+ * The hook returns a `mutate` function to trigger the update with given payload and exposes state flags.
  *
  * @example
  * ```tsx
  * import { useUpdateVariable } from '@figma-vars/hooks';
  *
- * function UpdateVariableButton({ variableId }: { variableId: string }) {
- *   const { mutate, isLoading, isSuccess, error } = useUpdateVariable();
- *
- *   const handleUpdate = () => {
- *     mutate({
- *       variableId,
- *       payload: {
- *         name: 'Updated Name',
- *         description: 'Updated description',
- *       },
- *     });
- *   };
+ * function UpdateVariableButton({ id }: { id: string }) {
+ *   const { mutate, isLoading, error } = useUpdateVariable();
  *
- *   if (!mutate) return <div>Not authorized. Figma token missing.</div>;
- *   if (isLoading) return <div>Updating variable…</div>;
- *   if (error) return <div style={{ color: 'red' }}>Error: {error.message}</div>;
- *   if (isSuccess) return <div>Variable updated successfully!</div>;
+ *   const onUpdate = () => mutate({ variableId: id, payload: { name: 'new-name' } });
  *
- *   return <button onClick={handleUpdate}>Update Variable</button>;
+ *   if (isLoading) return <div>Updating...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   return <button onClick={onUpdate}>Update Variable</button>;
  * }
  * ```
  *
  * @public
  */
-export declare const useUpdateVariable: () => import('..').MutationResult<any, UpdateVariableArgs>;
+export declare const useUpdateVariable: () => import('../types/mutations').MutationResult<unknown, {
+    variableId: string;
+    payload: UpdateVariablePayload;
+}>;
+//# sourceMappingURL=useUpdateVariable.d.ts.map

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

@@ -0,0 +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"}

package/dist/hooks/useVariableCollections.d.ts

@@ -33,3 +33,4 @@ export declare const useVariableCollections: () => {
     collections: FigmaCollection[];
     collectionsById: Record<string, FigmaCollection>;
 };
+//# sourceMappingURL=useVariableCollections.d.ts.map

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

@@ -0,0 +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"}

package/dist/hooks/useVariableModes.d.ts

@@ -30,3 +30,4 @@ import { UseVariableModesResult } from '../types/hooks';
  * @public
  */
 export declare const useVariableModes: () => UseVariableModesResult;
+//# sourceMappingURL=useVariableModes.d.ts.map

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

@@ -0,0 +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"}

package/dist/hooks/useVariables.d.ts

@@ -1,32 +1,16 @@
-import { SWRResponse } from 'swr';
-import { LocalVariablesResponse } from 'types';
+import { LocalVariablesResponse } from '../types/figma';
 /**
- * React hook that fetches all local variables, collections, and modes for the current Figma file via the Variables API.
+ * Hook to fetch and manage Figma Variables, including collections and modes.
  *
  * @remarks
- * Returns an object with SWR state for the Figma local variables endpoint, including:
- * - `data`: the variables response object (or undefined)
- * - `isLoading`: boolean loading state
- * - `isValidating`: boolean validation state
- * - `error`: error object (if any)
+ * This hook uses SWR for caching and revalidation. It fetches the variables for the
+ * 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.
  *
- * Use this as the single source of truth for all variables, collections, and modes within the current file context.
- *
- * @see {@link https://www.figma.com/developers/api#variables | Figma Variables API}
- *
- * @example
- * ```tsx
- * import { useVariables } from '@figma-vars/hooks';
- *
- * function VariablesPanel() {
- *   const { data, isLoading, error } = useVariables();
- *   if (isLoading) return <span>Loading variables…</span>;
- *   if (error) return <span style={{ color: 'red' }}>Error: {error.message}</span>;
- *   if (!data) return <span>No variables found.</span>;
- *   return <pre>{JSON.stringify(data, null, 2)}</pre>;
- * }
- * ```
+ * @returns SWR response object with `data`, `error`, `isLoading`, and `isValidating`.
  *
  * @public
  */
-export declare const useVariables: () => SWRResponse<LocalVariablesResponse>;
+export declare const useVariables: () => import('swr').SWRResponse<LocalVariablesResponse, any, import('swr').SWRConfiguration<LocalVariablesResponse, any, import('swr').BareFetcher<LocalVariablesResponse>> | undefined>;
+//# sourceMappingURL=useVariables.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useVariables.d.ts","sourceRoot":"","sources":["../../src/hooks/useVariables.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAG1D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,0LAoBxB,CAAC"}

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const b=require("react/jsx-runtime"),i=require("react"),_=require("swr"),p=i.createContext(void 0),g=({children:e,token:r,fileKey:t,fallbackFile:o})=>{const s=o===void 0?{token:r,fileKey:t}:{token:r,fileKey:t,fallbackFile:o};return b.jsx(p.Provider,{value:s,children:e})},l=()=>{const e=i.useContext(p);if(e===void 0)throw new Error("useFigmaTokenContext must be used within a FigmaVarsProvider");return e},h="https://api.figma.com",w=`${h}/v1/variables`,T=w,y=e=>`${w}/${e}`,v="application/json",A="X-FIGMA-TOKEN",u="A Figma API token is required.",I="An error occurred while fetching data from the Figma API.";async function V(e,r){if(!r)throw new Error(u);const t=await fetch(e,{method:"GET",headers:{[A]:r,"Content-Type":v}});if(!t.ok){let o=I;try{const s=await t.json();s!=null&&s.message&&(o=s.message)}catch{}throw new Error(o)}return t.json()}const E=()=>{const{token:e,fileKey:r,fallbackFile:t}=l(),o=async(n,a)=>t?typeof t=="string"?JSON.parse(t):t:V(n,a),s=e&&r?`https://api.figma.com/v1/files/${r}/variables/local`:null;return _(s&&e?[s,e]:null,s&&e?([n,a])=>o(n,a):()=>Promise.resolve(void 0))},R=()=>{const{data:e}=E(),r=i.useMemo(()=>e!=null&&e.meta?Object.values(e.meta.variableCollections):[],[e]),t=i.useMemo(()=>e!=null&&e.meta?e.meta.variableCollections:{},[e]);return{collections:r,collectionsById:t}},C=()=>{const{data:e}=E();return i.useMemo(()=>{const r=[],t={},o={};if(e!=null&&e.meta)for(const s of Object.values(e.meta.variableCollections)){r.push(...s.modes),t[s.id]=s.modes;for(const c of s.modes)o[c.modeId]=c}return{modes:r,modesByCollectionId:t,modesById:o}},[e])};function M(e,r){switch(r.type){case"loading":return{...e,status:"loading",error:null};case"success":return{...e,status:"success",data:r.payload};case"error":return{...e,status:"error",error:r.payload};default:return e}}const d=e=>{const r={status:"idle",data:null,error:null},[t,o]=i.useReducer(M,r);return{mutate:i.useCallback(async c=>{o({type:"loading"});try{const n=await e(c);return o({type:"success",payload:n}),n}catch(n){o({type:"error",payload:n});return}},[e]),...t,isLoading:t.status==="loading",isSuccess:t.status==="success",isError:t.status==="error"}};async function m(e,r,t,o){if(!r)throw new Error(u);const n={method:{CREATE:"POST",UPDATE:"PUT",DELETE:"DELETE"}[t],headers:{"Content-Type":"application/json",[A]:r}};o&&(n.body=JSON.stringify(o));const a=await fetch(`${h}${e}`,n);if(!a.ok){const f=await a.json().catch(()=>({}));throw new Error(f.err||f.message||"An API error occurred")}return a.status===204||!a.body?{}:a.json()}const P=()=>{const{token:e}=l();return d(async t=>{if(!e)throw new Error(u);return await m(T,e,"CREATE",t)})},F=()=>{const{token:e}=l();return d(async({variableId:t,payload:o})=>{if(!e)throw new Error(u);return await m(y(t),e,"UPDATE",o)})},O=()=>{const{token:e}=l();return d(async t=>{if(!e)throw new Error(u);return await m(y(t),e,"DELETE",void 0)})},S=()=>{const{token:e}=l();return d(async t=>{if(!e)throw new Error(u);return await m(T,e,"CREATE",t)})};function D(e,r){return e.filter(t=>{let o=!0;return r.resolvedType&&(o=o&&t.resolvedType===r.resolvedType),r.name&&(o=o&&t.name.includes(r.name)),o})}exports.FigmaVarsProvider=g;exports.filterVariables=D;exports.useBulkUpdateVariables=S;exports.useCreateVariable=P;exports.useDeleteVariable=O;exports.useUpdateVariable=F;exports.useVariableCollections=R;exports.useVariableModes=C;exports.useVariables=E;