@figma-vars/hooks 1.2.0 → 1.3.1

package/dist/index.d.ts

@@ -1,11 +1,936 @@
-export { default as useFigmaToken } from './hooks/useFigmaToken';
-export { useVariables } from './hooks/useVariables';
-export { useVariableCollections } from './hooks/useVariableCollections';
-export { useVariableModes } from './hooks/useVariableModes';
-export { bulkUpdateVariables } from './mutations/bulkUpdateVariables';
-export { createVariable } from './mutations/createVariable';
-export { deleteVariable } from './mutations/deleteVariable';
-export { updateVariable } from './mutations/updateVariable';
-export * from './types';
-export * from './utils/filterVariables';
-export { FigmaVarsProvider } from './contexts/FigmaTokenContext';
+import { JSX as JSX_2 } from 'react/jsx-runtime';
+import { MutationResult as MutationResult_2 } from '..';
+import { ReactNode } from 'react';
+
+/**
+ * The payload for the `bulkUpdateVariables` function.
+ * Allows creating, updating, and deleting multiple variables, collections, and modes in one call.
+ * This corresponds to the `POST /v1/files/:file_key/variables` endpoint.
+ * Note: Figma has deprecated this complex endpoint in favor of simpler, more granular ones.
+ * This type is kept for legacy purposes but its usage is not recommended.
+ *
+ * @typedef {Object} BulkUpdatePayload
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#post-variables|Figma API - Bulk Update Variables}
+ * @property {VariableCollectionChange[]} [variableCollections] A list of changes to variable collections.
+ * @property {VariableModeChange[]} [variableModes] A list of changes to variable modes.
+ * @property {VariableChange[]} [variables] A list of changes to variables.
+ * @property {VariableModeValue[]} [variableModeValues] A list of changes to variable values in specific modes.
+ */
+export declare interface BulkUpdatePayload {
+    /** A list of changes to variable collections. */
+    variableCollections?: VariableCollectionChange[];
+    /** A list of changes to variable modes. */
+    variableModes?: VariableModeChange[];
+    /** A list of changes to variables. */
+    variables?: VariableChange[];
+    /** A list of changes to variable values in specific modes. */
+    variableModeValues?: VariableModeValue[];
+}
+
+/**
+ * The response object returned by the `bulkUpdateVariables` function.
+ *
+ * @typedef {Object} BulkUpdateResponse
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#post-variables|Figma API - Bulk Update Variables}
+ * @property {boolean} error Whether an error occurred during the bulk update.
+ * @property {number} status The HTTP status code of the response.
+ * @property {string} [message] A message describing the result of the bulk update.
+ * @property {Object} [meta] Additional metadata about the bulk update.
+ * @property {Record<string, string>} [meta.tempIdToRealId] A mapping of temporary IDs to real IDs for created variables.
+ */
+export declare interface BulkUpdateResponse {
+    error: boolean;
+    status: number;
+    message?: string;
+    meta?: {
+        tempIdToRealId: Record<string, string>;
+    };
+}
+
+/**
+ * Represents a color in RGBA format.
+ *
+ * @typedef {Object} Color
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#color-object|Figma Color Object}
+ * @property {number} r The red channel value (0-1).
+ * @property {number} g The green channel value (0-1).
+ * @property {number} b The blue channel value (0-1).
+ * @property {number} a The alpha (opacity) channel value (0-1).
+ */
+export declare interface Color {
+    /** The red channel value (0-1). */
+    r: number;
+    /** The green channel value (0-1). */
+    g: number;
+    /** The blue channel value (0-1). */
+    b: number;
+    /** The alpha (opacity) channel value (0-1). */
+    a: number;
+}
+
+/**
+ * The payload for the `createVariable` function.
+ * Defines the properties for a new variable.
+ *
+ * @typedef {Object} CreateVariablePayload
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#post-variables|Figma API - Create Variable}
+ * @property {string} name The name of the new variable.
+ * @property {string} variableCollectionId The ID of the collection the new variable should be added to.
+ * @property {ResolvedType} resolvedType The underlying data type for the new variable.
+ * @property {string} [description] An optional description for the new variable.
+ * @property {boolean} [hiddenFromPublishing] Whether the new variable should be hidden when publishing. Defaults to `false`.
+ * @property {VariableScope[]} [scopes] The scopes in which this variable can be used.
+ * @property {Record<string, string>} [codeSyntax] Platform-specific code syntax for this variable.
+ * @property {Record<string, VariableValue>} [valuesByMode] Initial values for the variable by mode ID.
+ */
+export declare interface CreateVariablePayload {
+    /** The name of the new variable. */
+    name: string;
+    /** The ID of the collection the new variable should be added to. */
+    variableCollectionId: string;
+    /** The underlying data type for the new variable. */
+    resolvedType: ResolvedType;
+    /** An optional description for the new variable. */
+    description?: string;
+    /** Whether the new variable should be hidden when publishing. Defaults to `false`. */
+    hiddenFromPublishing?: boolean;
+    /** The scopes in which this variable can be used. */
+    scopes?: VariableScope[];
+    /** Platform-specific code syntax for this variable. */
+    codeSyntax?: Record<string, string>;
+}
+
+/**
+ * Represents a collection of Figma variables, which can contain multiple modes.
+ *
+ * @typedef {Object} FigmaCollection
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#variable-collection-object|Figma Variable Collection Object}
+ * @property {string} id The unique identifier for the collection.
+ * @property {string} name The name of the collection (e.g., "Brand Colors").
+ * @property {VariableMode[]} modes An array of modes available in this collection.
+ * @property {string} defaultModeId The ID of the default mode for this collection.
+ * @property {string[]} variableIds An array of variable IDs that belong to this collection.
+ * @property {boolean} hiddenFromPublishing Whether the collection is hidden when publishing the library.
+ * @property {string} updatedAt The timestamp of the last update.
+ */
+export declare interface FigmaCollection {
+    /** The unique identifier for the collection. */
+    id: string;
+    /** The name of the collection (e.g., "Brand Colors"). */
+    name: string;
+    /** An array of modes available in this collection. */
+    modes: VariableMode[];
+    /** The ID of the default mode for this collection. */
+    defaultModeId: string;
+    /** An array of variable IDs that belong to this collection. */
+    variableIds: string[];
+    /** Whether the collection is hidden when publishing the library. */
+    hiddenFromPublishing: boolean;
+    /** The timestamp of the last update. */
+    updatedAt: string;
+}
+
+/**
+ * A generic error shape for failed Figma API requests.
+ *
+ * @typedef {Object} FigmaError
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#error-handling|Figma API Error Handling}
+ * @property {number} statusCode The HTTP status code of the error.
+ * @property {string} message The error message from the API.
+ */
+export declare interface FigmaError {
+    /** The HTTP status code of the error. */
+    statusCode: number;
+    /** The error message from the API. */
+    message: string;
+}
+
+/* Excluded from this release type: FigmaTokenContextType */
+
+/**
+ * Represents a single Figma variable.
+ *
+ * @typedef {Object} FigmaVariable
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#variable-object|Figma Variable Object}
+ * @property {string} id The unique identifier for the variable.
+ * @property {string} name The name of the variable.
+ * @property {string} variableCollectionId The ID of the collection this variable belongs to.
+ * @property {ResolvedType} resolvedType The underlying data type of the variable.
+ * @property {Record<string, VariableValue>} valuesByMode A map of mode IDs to the variable's value in that mode.
+ * @property {string} description The description of the variable, as set in Figma.
+ * @property {boolean} hiddenFromPublishing Whether the variable is hidden when publishing the library.
+ * @property {VariableScope[]} scopes The scopes in which this variable can be used.
+ * @property {Record<string, string>} codeSyntax Platform-specific code syntax for this variable (e.g., for Web, iOS, Android).
+ * @property {string} updatedAt The timestamp of the last update.
+ */
+export declare interface FigmaVariable {
+    /** The unique identifier for the variable. */
+    id: string;
+    /** The name of the variable. */
+    name: string;
+    /** The ID of the collection this variable belongs to. */
+    variableCollectionId: string;
+    /** The underlying data type of the variable. */
+    resolvedType: ResolvedType;
+    /** A map of mode IDs to the variable's value in that mode. */
+    valuesByMode: Record<string, VariableValue>;
+    /** The description of the variable, as set in Figma. */
+    description: string;
+    /** Whether the variable is hidden when publishing the library. */
+    hiddenFromPublishing: boolean;
+    /** The scopes in which this variable can be used. */
+    scopes: VariableScope[];
+    /** Platform-specific code syntax for this variable (e.g., for Web, iOS, Android). */
+    codeSyntax: Record<string, string>;
+    /** The timestamp of the last update. */
+    updatedAt: string;
+}
+
+/**
+ * Provides the Figma token and file key to all descendant hooks.
+ * This component should be placed at the root of your application or any component tree
+ * that needs to interact with the Figma Variables API.
+ *
+ * @function FigmaVarsProvider
+ * @memberof Providers
+ * @since 1.0.0
+ * @param {FigmaVarsProviderProps} props - The provider props
+ * @param {string} props.token - The Figma Personal Access Token
+ * @param {string} props.fileKey - The Figma file key from the file URL
+ * @param {React.ReactNode} props.children - The child components that will have access to the context
+ * @returns {JSX.Element} The provider component
+ * @see {@link https://www.figma.com/developers/api#authentication|Figma API Authentication}
+ *
+ * @example
+ * ```tsx
+ * import { FigmaVarsProvider } from '@figma-vars/hooks';
+ *
+ * function App() {
+ *   const token = process.env.REACT_APP_FIGMA_TOKEN;
+ *   const fileKey = 'abc123def456'; // From Figma file URL
+ *
+ *   return (
+ *     <FigmaVarsProvider token={token} fileKey={fileKey}>
+ *       <Dashboard />
+ *       <VariableEditor />
+ *     </FigmaVarsProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With Next.js and environment variables
+ * import { FigmaVarsProvider } from '@figma-vars/hooks';
+ *
+ * export default function MyApp({ Component, pageProps }) {
+ *   return (
+ *     <FigmaVarsProvider
+ *       token={process.env.NEXT_PUBLIC_FIGMA_TOKEN}
+ *       fileKey={process.env.NEXT_PUBLIC_FIGMA_FILE_KEY}
+ *     >
+ *       <Component {...pageProps} />
+ *     </FigmaVarsProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare const FigmaVarsProvider: ({ children, token, fileKey, }: FigmaVarsProviderProps) => JSX_2.Element;
+
+/**
+ * Props for the `FigmaVarsProvider` component.
+ *
+ * @typedef {Object} FigmaVarsProviderProps
+ * @memberof Types
+ * @since 1.0.0
+ * @property {ReactNode} children The child components that will have access to the context.
+ * @property {string | null} token The Figma Personal Access Token for API authentication.
+ * @property {string | null} fileKey The Figma file key extracted from the file URL.
+ */
+export declare interface FigmaVarsProviderProps {
+    /** The child components that will have access to the context. */
+    children: ReactNode;
+    /**
+     * Your Figma Personal Access Token.
+     * @see https://www.figma.com/developers/api#authentication
+     */
+    token: string | null;
+    /**
+     * The unique identifier of the Figma file you want to access.
+     * You can get this from the file's URL.
+     */
+    fileKey: string | null;
+}
+
+/**
+ * Filters an array of Figma variables based on specified criteria.
+ * This utility can filter by variable type, a partial name match, or both.
+ *
+ * @function filterVariables
+ * @memberof Utils
+ * @since 1.0.0
+ * @param {FigmaVariable[]} variables The array of `FigmaVariable` objects to filter.
+ * @param {Object} criteria An object specifying the filter criteria.
+ * @param {ResolvedType} [criteria.resolvedType] The variable type (e.g., 'COLOR', 'FLOAT') to filter by.
+ * @param {string} [criteria.name] A string to search for within the variable names (case-sensitive).
+ * @returns {FigmaVariable[]} A new array containing only the variables that match the criteria.
+ * @see {@link https://www.figma.com/developers/api#variable-object|Figma Variable Object}
+ *
+ * @example
+ * ```typescript
+ * import { filterVariables } from 'utils/filterVariables';
+ *
+ * const allVariables = [
+ *   { name: 'primary-color', resolvedType: 'COLOR', id: '1:1', ... },
+ *   { name: 'font-size-large', resolvedType: 'FLOAT', id: '1:2', ... },
+ *   { name: 'secondary-color', resolvedType: 'COLOR', id: '1:3', ... }
+ * ];
+ *
+ * // Filter by type
+ * const colorVariables = filterVariables(allVariables, {
+ *   resolvedType: 'COLOR'
+ * });
+ * // Returns: [primary-color, secondary-color]
+ *
+ * // Filter by name (partial match)
+ * const fontVariables = filterVariables(allVariables, {
+ *   name: 'font'
+ * });
+ * // Returns: [font-size-large]
+ *
+ * // Filter by both type and name
+ * const primaryColors = filterVariables(allVariables, {
+ *   resolvedType: 'COLOR',
+ *   name: 'primary'
+ * });
+ * // Returns: [primary-color]
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use with the useVariables hook
+ * import { useVariables, filterVariables } from 'utils';
+ *
+ * function ColorVariablesList() {
+ *   const { variables } = useVariables();
+ *
+ *   const colorVariables = filterVariables(variables, {
+ *     resolvedType: 'COLOR'
+ *   });
+ *
+ *   return (
+ *     <ul>
+ *       {colorVariables.map(variable => (
+ *         <li key={variable.id}>{variable.name}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export declare function filterVariables(variables: FigmaVariable[], criteria: {
+    resolvedType?: ResolvedType;
+    name?: string;
+}): FigmaVariable[];
+
+/**
+ * The structure of the successful response from the Figma API's `/v1/files/{file_key}/variables/local` endpoint.
+ *
+ * @typedef {Object} LocalVariablesResponse
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#variables-endpoint|Figma Variables Endpoint}
+ * @property {Object} meta Contains the metadata about the variables and collections.
+ * @property {Record<string, FigmaCollection>} meta.variableCollections A map of collection IDs to `FigmaCollection` objects.
+ * @property {Record<string, FigmaVariable>} meta.variables A map of variable IDs to `FigmaVariable` objects.
+ */
+export declare interface LocalVariablesResponse {
+    /** Contains the metadata about the variables and collections. */
+    meta: {
+        /** A map of collection IDs to `FigmaCollection` objects. */
+        variableCollections: Record<string, FigmaCollection>;
+        /** A map of variable IDs to `FigmaVariable` objects. */
+        variables: Record<string, FigmaVariable>;
+    };
+}
+
+/**
+ * The result object returned by the `useMutation` hook.
+ * @template TData The type of data returned by the mutation.
+ * @template TPayload The type of the payload passed to the mutate function.
+ *
+ * @typedef {Object} MutationResult
+ * @memberof Types
+ * @since 1.0.0
+ * @property {(payload: TPayload) => Promise<TData | undefined>} mutate A function to trigger the mutation.
+ * @property {'idle' | 'loading' | 'success' | 'error'} status The current status of the mutation.
+ * @property {TData | null} data The data returned by the mutation, or null if the mutation has not completed.
+ * @property {Error | null} error The error returned by the mutation, or null if the mutation was successful.
+ * @property {boolean} isLoading Whether the mutation is currently loading.
+ * @property {boolean} isSuccess Whether the mutation was successful.
+ * @property {boolean} isError Whether the mutation resulted in an error.
+ */
+export declare interface MutationResult<TData, TPayload> {
+    mutate: (payload: TPayload) => Promise<TData | undefined>;
+    status: 'idle' | 'loading' | 'success' | 'error';
+    data: TData | null;
+    error: Error | null;
+    isLoading: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+}
+
+/**
+ * Represents the state of a mutation operation.
+ * @template TData The type of data returned by the mutation.
+ * @template TError The type of error returned by the mutation.
+ *
+ * @typedef {Object} MutationState
+ * @memberof Types
+ * @since 1.0.0
+ * @property {'idle' | 'loading' | 'success' | 'error'} status The current status of the mutation.
+ * @property {TData | null} data The data returned by the mutation, or null if the mutation has not completed.
+ * @property {Error | null} error The error returned by the mutation, or null if the mutation was successful.
+ */
+export declare interface MutationState<TData> {
+    status: 'idle' | 'loading' | 'success' | 'error';
+    data: TData | null;
+    error: Error | null;
+}
+
+/**
+ * @fileoverview TypeScript type definitions for the Figma Variables REST API.
+ * These types match the official Figma API specification for variables, collections, and modes.
+ * @see {@link https://www.figma.com/developers/api#variables|Figma Variables API Documentation}
+ * @since 1.0.0
+ */
+/**
+ * The resolved type of a Figma variable.
+ * Determines what kind of value the variable can hold.
+ *
+ * @typedef {string} ResolvedType
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#variable-object|Figma Variable Object}
+ */
+export declare type ResolvedType = 'BOOLEAN' | 'FLOAT' | 'STRING' | 'COLOR';
+
+declare type UpdateVariableArgs = {
+    variableId: string;
+    payload: UpdateVariablePayload;
+};
+
+/**
+ * The payload for the `updateVariable` function.
+ * All properties are optional.
+ *
+ * @typedef {Object} UpdateVariablePayload
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#patch-variables|Figma API - Update Variable}
+ * @property {string} [name] The new name for the variable.
+ * @property {string} [description] The new description for the variable.
+ * @property {boolean} [hiddenFromPublishing] The new hidden status for the variable.
+ * @property {VariableScope[]} [scopes] The new scopes for the variable.
+ * @property {Record<string, string>} [codeSyntax] The new code syntax for the variable.
+ * @property {Record<string, VariableValue>} [valuesByMode] New values for the variable by mode ID.
+ */
+export declare interface UpdateVariablePayload {
+    /** The new name for the variable. */
+    name?: string;
+    /** The new description for the variable. */
+    description?: string;
+    /** The new hidden status for the variable. */
+    hiddenFromPublishing?: boolean;
+    /** The new scopes for the variable. */
+    scopes?: VariableScope[];
+    /** The new code syntax for the variable. */
+    codeSyntax?: Record<string, string>;
+}
+
+/**
+ * Updates multiple variables in the Figma file in a single request.
+ *
+ * This hook provides a stateful API to perform a bulk update, returning the mutation's
+ * current state including `isLoading`, `isSuccess`, and `isError`.
+ *
+ * @function useBulkUpdateVariables
+ * @memberof Hooks
+ * @since 1.0.0
+ * @returns {MutationResult<any, BulkUpdatePayload>} The mutation object with state and trigger function.
+ * @see {@link https://www.figma.com/developers/api#post-variables|Figma Variables API - Bulk Update Variables}
+ * @see {@link useMutation} - The underlying mutation hook
+ *
+ * @example
+ * ```tsx
+ * import { useBulkUpdateVariables } from '@figma-vars/hooks';
+ *
+ * function BulkVariableEditor() {
+ *   const { mutate, isLoading, isSuccess, error } = useBulkUpdateVariables();
+ *
+ *   const handleBulkUpdate = () => {
+ *     mutate({
+ *       variableIds: ['VariableID:123:456', 'VariableID:123:457'],
+ *       variableCollectionId: 'VariableCollectionId:123:456',
+ *       updates: {
+ *         'VariableID:123:456': {
+ *           name: 'Primary Color Updated',
+ *           description: 'Updated primary brand color'
+ *         },
+ *         'VariableID:123:457': {
+ *           name: 'Secondary Color Updated',
+ *           description: 'Updated secondary brand color'
+ *         }
+ *       }
+ *     });
+ *   };
+ *
+ *   if (isLoading) return <div>Updating variables...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (isSuccess) return <div>Variables updated successfully!</div>;
+ *
+ *   return <button onClick={handleBulkUpdate}>Update All Variables</button>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Bulk update color variables with new values
+ * const { mutate } = useBulkUpdateVariables();
+ *
+ * mutate({
+ *   variableIds: ['VariableID:123:456', 'VariableID:123:457'],
+ *   variableCollectionId: 'VariableCollectionId:123:456',
+ *   updates: {
+ *     'VariableID:123:456': {
+ *       valuesByMode: {
+ *         '42:0': { r: 0.2, g: 0.4, b: 0.8, a: 1 }
+ *       }
+ *     },
+ *     'VariableID:123:457': {
+ *       valuesByMode: {
+ *         '42:0': { r: 0.8, g: 0.4, b: 0.2, a: 1 }
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare const useBulkUpdateVariables: () => MutationResult_2<any, BulkUpdatePayload>;
+
+/**
+ * Creates a new variable in the Figma file.
+ *
+ * This hook provides a stateful API to create a new variable, returning the mutation's
+ * current state including `isLoading`, `isSuccess`, `isError`, and the created data.
+ *
+ * @function useCreateVariable
+ * @memberof Hooks
+ * @since 1.0.0
+ * @returns {MutationResult<any, CreateVariablePayload>} The mutation object with state and trigger function.
+ * @see {@link https://www.figma.com/developers/api#post-variables|Figma Variables API - Create Variable}
+ * @see {@link useMutation} - The underlying mutation hook
+ *
+ * @example
+ * ```tsx
+ * import { useCreateVariable } from '@figma-vars/hooks';
+ *
+ * function VariableCreator() {
+ *   const { mutate, isLoading, isSuccess, error, data } = 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 }
+ *       }
+ *     });
+ *   };
+ *
+ *   if (isLoading) return <div>Creating variable...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (isSuccess) return <div>Variable created: {data?.name}</div>;
+ *
+ *   return <button onClick={handleCreate}>Create Variable</button>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Create a string variable
+ * const { mutate } = useCreateVariable();
+ *
+ * mutate({
+ *   name: 'Button Text',
+ *   variableCollectionId: 'VariableCollectionId:123:456',
+ *   resolvedType: 'STRING',
+ *   description: 'Default button text content',
+ *   valuesByMode: {
+ *     '42:0': 'Click me'
+ *   },
+ *   scopes: ['TEXT_CONTENT']
+ * });
+ * ```
+ */
+export declare const useCreateVariable: () => MutationResult_2<any, CreateVariablePayload>;
+
+/**
+ * Deletes a variable from the Figma file by its ID.
+ *
+ * This hook provides a stateful API to delete a variable, returning the mutation's
+ * current state including `isLoading`, `isSuccess`, and `isError`.
+ *
+ * @function useDeleteVariable
+ * @memberof Hooks
+ * @since 1.0.0
+ * @returns {MutationResult<void, string>} The mutation object with state and trigger function.
+ * @see {@link https://www.figma.com/developers/api#delete-variables|Figma Variables API - Delete Variable}
+ * @see {@link useMutation} - The underlying mutation hook
+ *
+ * @example
+ * ```tsx
+ * import { useDeleteVariable } from './useDeleteVariable';
+ *
+ * function VariableDeleter({ variableId }) {
+ *   const { mutate, isLoading, isSuccess, error } = useDeleteVariable();
+ *
+ *   const handleDelete = () => {
+ *     if (confirm('Are you sure you want to delete this variable?')) {
+ *       mutate(variableId);
+ *     }
+ *   };
+ *
+ *   if (isLoading) return <div>Deleting variable...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (isSuccess) return <div>Variable deleted successfully!</div>;
+ *
+ *   return <button onClick={handleDelete}>Delete Variable</button>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Delete a variable by ID
+ * const { mutate, isLoading } = useDeleteVariable();
+ *
+ * const deleteVariable = (id: string) => {
+ *   mutate(id); // Pass the variable ID directly
+ * };
+ *
+ * // Usage
+ * deleteVariable('VariableID:123:456');
+ * ```
+ */
+export declare const useDeleteVariable: () => MutationResult_2<any, string>;
+
+/**
+ * Retrieves the Figma API token from the FigmaVarsProvider.
+ * This hook must be used within a component wrapped by FigmaVarsProvider.
+ *
+ * @function useFigmaToken
+ * @memberof Hooks
+ * @since 1.0.0
+ * @returns {string | null} The Figma Personal Access Token, or `null` if it has not been provided.
+ * @see {@link https://www.figma.com/developers/api#authentication|Figma API Authentication}
+ * @see {@link FigmaVarsProvider} - The provider component that supplies the token
+ *
+ * @example
+ * ```tsx
+ * import { useFigmaToken } from './useFigmaToken';
+ *
+ * function CustomAPIComponent() {
+ *   const figmaToken = useFigmaToken();
+ *
+ *   const makeCustomAPICall = async () => {
+ *     if (!figmaToken) {
+ *       console.error('No Figma token available');
+ *       return;
+ *     }
+ *
+ *     // Use token for custom API calls
+ *     const response = await fetch('https://api.figma.com/v1/me', {
+ *       headers: {
+ *         'X-FIGMA-TOKEN': figmaToken
+ *       }
+ *     });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       {figmaToken ? 'Token available' : 'No token provided'}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Check token availability before making API calls
+ * const MyComponent = () => {
+ *   const figmaToken = useFigmaToken();
+ *
+ *   if (!figmaToken) {
+ *     return <div>Please provide a Figma token</div>;
+ *   }
+ *
+ *   return <div>Ready to interact with Figma API</div>;
+ * };
+ * ```
+ */
+export declare const useFigmaToken: () => string | null;
+
+/**
+ * Updates an existing Figma variable.
+ *
+ * This hook provides a stateful API to update a variable, returning the mutation's
+ * current state including `isLoading`, `isSuccess`, `isError`, and the updated data.
+ *
+ * @function useUpdateVariable
+ * @memberof Hooks
+ * @since 1.0.0
+ * @returns {MutationResult<any, UpdateVariableArgs>} The mutation object with state and trigger function.
+ * @see {@link https://www.figma.com/developers/api#put-variables|Figma Variables API - Update Variable}
+ * @see {@link useMutation} - The underlying mutation hook
+ *
+ * @example
+ * ```tsx
+ * import { useUpdateVariable } from '@figma-vars/hooks';
+ *
+ * function VariableEditor() {
+ *   const { mutate, isLoading, isSuccess, error } = useUpdateVariable();
+ *
+ *   const handleUpdate = () => {
+ *     mutate({
+ *       variableId: 'VariableID:123:456',
+ *       payload: {
+ *         name: 'Updated Variable Name',
+ *         description: 'Updated description'
+ *       }
+ *     });
+ *   };
+ *
+ *   if (isLoading) return <div>Updating variable...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (isSuccess) return <div>Variable updated successfully!</div>;
+ *
+ *   return <button onClick={handleUpdate}>Update Variable</button>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Update variable with new values
+ * const { mutate } = useUpdateVariable();
+ *
+ * mutate({
+ *   variableId: 'VariableID:123:456',
+ *   payload: {
+ *     name: 'Primary Color',
+ *     description: 'Main brand color',
+ *     valuesByMode: {
+ *       '42:0': { r: 0.2, g: 0.4, b: 0.8, a: 1 }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare const useUpdateVariable: () => MutationResult_2<unknown, UpdateVariableArgs>;
+
+/**
+ * A memoized selector hook to access variable collections from the data fetched by `useVariables`.
+ *
+ * This hook is a lightweight, performant way to get only collection data. It avoids
+ * unnecessary re-renders in components that only care about collections, as it will only
+ * update when the collection data itself changes.
+ *
+ * @returns {{collections: FigmaCollection[], collectionsById: Record<string, FigmaCollection>}} An object containing the collections in different formats.
+ *
+ * @example
+ * ```tsx
+ * const { collectionsById } = useVariableCollections();
+ * const collection = collectionsById['VariableCollectionId:123:456'];
+ *
+ * if (!collection) return <div>Collection not found.</div>;
+ *
+ * return <div>{collection.name}</div>
+ * ```
+ */
+export declare const useVariableCollections: () => {
+    collections: FigmaCollection[];
+    collectionsById: Record<string, FigmaCollection>;
+};
+
+/**
+ * A memoized selector hook to access and process variable modes from the data fetched by `useVariables`.
+ *
+ * This hook is a lightweight, performant way to get only mode data. It avoids
+ * unnecessary re-renders in components that only care about modes, as it will only
+ * update when the mode data itself changes. It provides modes in several useful formats.
+ *
+ * @returns {UseVariableModesResult} An object containing the modes in different formats.
+ *
+ * @example
+ * ```tsx
+ * const { modesById, modesByCollectionId } = useVariableModes();
+ * const lightMode = modesById['42:0'];
+ * const collectionModes = modesByCollectionId['VariableCollectionId:123:456'];
+ *
+ * if (!lightMode) return <div>Mode not found.</div>;
+ *
+ * return <div>Mode: {lightMode.name}</div>
+ * ```
+ */
+export declare const useVariableModes: () => UseVariableModesResult;
+
+/**
+ * The return type for the `useVariableModes` hook.
+ * Provides multiple ways to access and organize variable modes from Figma collections.
+ *
+ * @typedef {Object} UseVariableModesResult
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link useVariableModes} - The hook that returns this type
+ * @property {VariableMode[]} modes A flat array of all modes across all collections.
+ * @property {Record<string, VariableMode[]>} modesByCollectionId A map of collection IDs to an array of modes belonging to that collection.
+ * @property {Record<string, VariableMode>} modesById A map of mode IDs to the corresponding mode object for quick lookups.
+ */
+export declare interface UseVariableModesResult {
+    /** A flat array of all modes across all collections. */
+    modes: VariableMode[];
+    /** A map of collection IDs to an array of modes belonging to that collection. */
+    modesByCollectionId: Record<string, VariableMode[]>;
+    /** A map of mode IDs to the corresponding mode object for quick lookups. */
+    modesById: Record<string, VariableMode>;
+}
+
+/**
+ * Fetches all local variables, collections, and modes for the file specified in the `FigmaVarsProvider`.
+ * This is the primary data-fetching hook and serves as the foundation for other hooks like `useVariableCollections` and `useVariableModes`.
+ *
+ * "Local variables" are all variables and collections defined in the current file.
+ *
+ * It uses `swr` for efficient data fetching, caching, and revalidation.
+ *
+ * @returns {{data: LocalVariablesResponse | undefined, isLoading: boolean, isValidating: boolean, error: Error | undefined}} The response from `useSWR` for the local variables endpoint.
+ * @see {@link https://www.figma.com/developers/api#get-local-variables-v1|Figma Variables API Documentation}
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, error } = useVariables();
+ *
+ * if (isLoading) return <div>Loading variables...</div>;
+ * if (error) return <div>Error fetching variables: {error.message}</div>;
+ *
+ * const collections = data ? Object.values(data.meta.variableCollections) : [];
+ * console.log(collections);
+ * ```
+ */
+export declare const useVariables: () => {
+    data: LocalVariablesResponse | undefined;
+    isLoading: boolean;
+    isValidating: boolean;
+    error: any;
+};
+
+/* Excluded from this release type: VariableAction */
+
+/**
+ * Represents an alias to another Figma variable.
+ * This is used when a variable's value is set to reference another variable.
+ *
+ * @typedef {Object} VariableAlias
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#variable-object|Figma Variable Object}
+ * @property {string} type The type of the value, indicating it's a variable alias.
+ * @property {string} id The ID of the variable being referenced.
+ */
+export declare interface VariableAlias {
+    /** The type of the value, indicating it's a variable alias. */
+    type: 'VARIABLE_ALIAS';
+    /** The ID of the variable being referenced. */
+    id: string;
+}
+
+/* Excluded from this release type: VariableChange */
+
+/* Excluded from this release type: VariableCollectionChange */
+
+/**
+ * Represents a single mode within a variable collection.
+ *
+ * @typedef {Object} VariableMode
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#variable-collection-object|Figma Variable Collection Object}
+ * @property {string} modeId The unique identifier for the mode.
+ * @property {string} name The name of the mode (e.g., "Light", "Dark").
+ */
+export declare interface VariableMode {
+    /** The unique identifier for the mode. */
+    modeId: string;
+    /** The name of the mode (e.g., "Light", "Dark"). */
+    name: string;
+}
+
+/* Excluded from this release type: VariableModeChange */
+
+/**
+ * A change to a variable's value in a specific mode in a bulk update.
+ *
+ * @typedef {Object} VariableModeValue
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#patch-variables|Figma API - Update Variable Value}
+ * @property {string} variableId The ID of the variable to update.
+ * @property {string} modeId The ID of the mode to update.
+ * @property {VariableValue} value The new value for the variable in this mode.
+ */
+export declare interface VariableModeValue {
+    /** The ID of the variable to update. */
+    variableId: string;
+    /** The ID of the mode to update. */
+    modeId: string;
+    /** The new value for the variable in this mode. */
+    value: VariableValue;
+}
+
+/**
+ * The scopes where a Figma variable can be applied.
+ * `ALL_SCOPES` is a general-purpose scope. Other values restrict the variable to specific properties.
+ *
+ * @typedef {string} VariableScope
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#variable-object|Figma Variable Object}
+ */
+export declare type VariableScope = 'ALL_SCOPES' | 'TEXT_CONTENT' | 'CORNER_RADIUS' | 'WIDTH_HEIGHT' | 'GAP' | 'STROKE_FLOAT' | 'OPACITY' | 'EFFECT_FLOAT' | 'FONT_WEIGHT' | 'FONT_SIZE' | 'LINE_HEIGHT' | 'LETTER_SPACING' | 'PARAGRAPH_SPACING' | 'PARAGRAPH_INDENT' | 'FONT_FAMILY' | 'FONT_STYLE' | 'FONT_VARIATIONS' | 'ALL_FILLS' | 'FRAME_FILL' | 'SHAPE_FILL' | 'TEXT_FILL' | 'STROKE_COLOR' | 'EFFECT_COLOR';
+
+/**
+ * The possible value types for a variable in a specific mode.
+ * It can be a primitive value, a color object, or an alias to another variable.
+ *
+ * @typedef {(string|boolean|number|Color|VariableAlias)} VariableValue
+ * @memberof Types
+ * @since 1.0.0
+ * @see {@link https://www.figma.com/developers/api#variable-object|Figma Variable Object}
+ */
+export declare type VariableValue = string | boolean | number | Color | VariableAlias;
+
+export { }