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

package/README.md

@@ -31,14 +31,14 @@ Built for the modern web, this library provides a suite of hooks to fetch, manag
 
 ## 🧱 Architecture Highlights
 
-✅ **100% Test Coverage** - Comprehensive test suite with 78 tests covering all hooks, utilities, and edge cases via Vitest
-✅ **Consistent Error Handling** - Standardized error propagation with clear messages from the Figma API
-✅ **Strictly Typed APIs** - Modern TypeScript best practices with full type inference and autocompletion
-✅ **Predictable Hook Signatures** - Consistent, composable patterns designed for safe React integrations
-✅ **Developer-First Architecture** - Clean folder structure, path aliases, and logical component separation
-✅ **React Ecosystem** - Built specifically for React apps, Storybook, Next.js, and design system dashboards
-✅ **Ergonomic DX** - Intuitive API that's easy to use in both prototype and production environments
-✅ **Minimal Dependencies** - Leverages SWR for caching with careful dependency selection for optimal bundle size
+- ✅ **100% Test Coverage** - Comprehensive test suite with 78 tests covering all hooks, utilities, and edge cases via Vitest
+- ✅ **Consistent Error Handling** - Standardized error propagation with clear messages from the Figma API
+- ✅ **Strictly Typed APIs** - Modern TypeScript best practices with full type inference and autocompletion
+- ✅ **Predictable Hook Signatures** - Consistent, composable patterns designed for safe React integrations
+- ✅ **Developer-First Architecture** - Clean folder structure, path aliases, and logical component separation
+- ✅ **React Ecosystem** - Built specifically for React apps, Storybook, Next.js, and design system dashboards
+- ✅ **Ergonomic DX** - Intuitive API that's easy to use in both prototype and production environments
+- ✅ **Minimal Dependencies** - Leverages SWR for caching with careful dependency selection for optimal bundle size
 
 ---
 

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,14 @@
-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.
  *
- * 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;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,0LAUxB,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),v=({children:e,token:o,fileKey:t,fallbackFile:r})=>{const s=r===void 0?{token:o,fileKey:t}:{token:o,fileKey:t,fallbackFile:r};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,A=e=>`${w}/${e}`,I="application/json",y="X-FIGMA-TOKEN",c="A Figma API token is required.",g="An error occurred while fetching data from the Figma API.";async function V(e,o){if(!o)throw new Error(c);const t=await fetch(e,{method:"GET",headers:{[y]:o,"Content-Type":I}});if(!t.ok){let r=g;try{const s=await t.json();s!=null&&s.message&&(r=s.message)}catch{}throw new Error(r)}return t.json()}const E=()=>{const{token:e,fileKey:o}=l(),t=e&&o?`https://api.figma.com/v1/files/${o}/variables/local`:null;return _(t&&e?[t,e]:null,t&&e?([s,n])=>V(s,n):()=>Promise.resolve(void 0))},R=()=>{const{data:e}=E(),o=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:o,collectionsById:t}},C=()=>{const{data:e}=E();return i.useMemo(()=>{const o=[],t={},r={};if(e!=null&&e.meta)for(const s of Object.values(e.meta.variableCollections)){o.push(...s.modes),t[s.id]=s.modes;for(const n of s.modes)r[n.modeId]=n}return{modes:o,modesByCollectionId:t,modesById:r}},[e])};function M(e,o){switch(o.type){case"loading":return{...e,status:"loading",error:null};case"success":return{...e,status:"success",data:o.payload};case"error":return{...e,status:"error",error:o.payload};default:return e}}const d=e=>{const o={status:"idle",data:null,error:null},[t,r]=i.useReducer(M,o);return{mutate:i.useCallback(async n=>{r({type:"loading"});try{const a=await e(n);return r({type:"success",payload:a}),a}catch(a){r({type:"error",payload:a});return}},[e]),...t,isLoading:t.status==="loading",isSuccess:t.status==="success",isError:t.status==="error"}};async function m(e,o,t,r){if(!o)throw new Error(c);const a={method:{CREATE:"POST",UPDATE:"PUT",DELETE:"DELETE"}[t],headers:{"Content-Type":"application/json",[y]:o}};r&&(a.body=JSON.stringify(r));const u=await fetch(`${h}${e}`,a);if(!u.ok){const f=await u.json().catch(()=>({}));throw new Error(f.err||f.message||"An API error occurred")}return u.status===204||!u.body?{}:u.json()}const P=()=>{const{token:e}=l();return d(async t=>{if(!e)throw new Error(c);return await m(T,e,"CREATE",t)})},O=()=>{const{token:e}=l();return d(async({variableId:t,payload:r})=>{if(!e)throw new Error(c);return await m(A(t),e,"UPDATE",r)})},D=()=>{const{token:e}=l();return d(async t=>{if(!e)throw new Error(c);return await m(A(t),e,"DELETE",void 0)})},F=()=>{const{token:e}=l();return d(async t=>{if(!e)throw new Error(c);return await m(T,e,"CREATE",t)})};function S(e,o){return e.filter(t=>{let r=!0;return o.resolvedType&&(r=r&&t.resolvedType===o.resolvedType),o.name&&(r=r&&t.name.includes(o.name)),r})}exports.FigmaVarsProvider=v;exports.filterVariables=S;exports.useBulkUpdateVariables=F;exports.useCreateVariable=P;exports.useDeleteVariable=D;exports.useUpdateVariable=O;exports.useVariableCollections=R;exports.useVariableModes=C;exports.useVariables=E;

package/dist/index.d.cts

@@ -0,0 +1,81 @@
+/**
+ * @packageDocumentation
+ *
+ * Entry point for **@figma-vars/hooks** — a modern, idiomatic React hooks library for Figma Variables via the REST API.
+ *
+ * @remarks
+ * Exposes all providers, hooks, utilities, and types needed to build robust Figma variable dashboards, plugins, and design system tools.
+ * Each export group below has its own summary and real-world usage example for rapid onboarding and type-safe integration.
+ *
+ * MIT Licensed. Author: Mark Learst.
+ * Docs: {@link https://github.com/marklearst/figma-vars-hooks}
+ */
+/**
+ * React context provider for Figma API authentication and file scoping.
+ *
+ * @remarks
+ * Wrap your app in this provider to supply the Figma Personal Access Token and file key globally—all hooks and utilities will use this context.
+ * This ensures seamless, type-safe access to the Figma REST API for all child components.
+ *
+ * @example
+ * ```tsx
+ * import { FigmaVarsProvider } from '@figma-vars/hooks';
+ *
+ * function App() {
+ *   return (
+ *     <FigmaVarsProvider token={process.env.FIGMA_TOKEN} fileKey="your-file-key">
+ *       <YourComponent />
+ *     </FigmaVarsProvider>
+ *   );
+ * }
+ * ```
+ */
+export { FigmaVarsProvider } from 'contexts';
+/**
+ * Core React hooks for interacting with Figma Variables.
+ *
+ * @remarks
+ * Hooks for fetching, creating, updating, deleting, and bulk updating Figma variables—plus selectors for collections and modes.
+ * All hooks share idiomatic return shapes and error handling for rapid UI and API integration.
+ * Use these hooks to build dashboards, plugins, and design system tools with minimal boilerplate and maximum type safety.
+ *
+ * @see {@link https://www.figma.com/developers/api#variables | Figma Variables API}
+ *
+ * @example
+ * ```tsx
+ * import { useVariables, useCreateVariable } from '@figma-vars/hooks';
+ *
+ * function Example() {
+ *   const { data, isLoading } = useVariables();
+ *   const { mutate } = useCreateVariable();
+ *   // Use the hooks in your component logic
+ * }
+ * ```
+ */
+export { useVariables, useVariableCollections, useVariableModes, useCreateVariable, useUpdateVariable, useDeleteVariable, useBulkUpdateVariables, } from 'hooks';
+/**
+ * Utility functions for Figma Variable management.
+ *
+ * @remarks
+ * Helpers like `filterVariables` for searching and filtering variable lists. All utilities are stateless and type-safe—use for UI filtering, scripting, and dashboard logic.
+ *
+ * @example
+ * ```ts
+ * import { filterVariables } from '@figma-vars/hooks';
+ * const filtered = filterVariables(variables, { resolvedType: 'COLOR' });
+ * ```
+ */
+export { filterVariables } from 'utils';
+/**
+ * All official TypeScript types for advanced usage and type-safe integration.
+ *
+ * @remarks
+ * All Figma domain models, mutation payloads/results, and provider context types—imported as needed for advanced TypeScript, API wrappers, plugins, and custom hooks.
+ *
+ * @example
+ * ```ts
+ * import type { FigmaVariable, CreateVariablePayload } from '@figma-vars/hooks';
+ * ```
+ */
+export * from 'types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.mts

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

package/dist/index.d.ts

@@ -78,3 +78,4 @@ export { filterVariables } from 'utils';
  * ```
  */
 export * from 'types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,OAAO,CAAC;AAEf;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAExC;;;;;;;;;;GAUG;AACH,cAAc,OAAO,CAAC"}