@figma-vars/hooks 1.3.3 → 1.4.3

package/dist/index.d.ts

@@ -1,1221 +0,0 @@
-import { JSX as JSX_2 } from 'react/jsx-runtime';
-import { MutationResult as MutationResult_2 } from '../types/mutations';
-import { MutationResult as MutationResult_3 } 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 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.
- */
-declare interface BulkUpdatePayload_2 {
-    /** A list of changes to variable collections. */
-    variableCollections?: VariableCollectionChange_2[];
-    /** A list of changes to variable modes. */
-    variableModes?: VariableModeChange_2[];
-    /** A list of changes to variables. */
-    variables?: VariableChange_2[];
-    /** A list of changes to variable values in specific modes. */
-    variableModeValues?: VariableModeValue_2[];
-}
-
-/**
- * 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
-}
-
-/**
- * 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).
- */
-declare interface Color_2 {
-    /** 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>
-}
-
-/**
- * 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.
- */
-declare interface CreateVariablePayload_2 {
-    /** 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_2;
-    /** 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_2[];
-    /** 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_2) => 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
-}
-
-/**
- * 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.
- */
-declare interface FigmaVarsProviderProps_2 {
-    /** 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'
-
-/**
- * @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}
- */
-declare type ResolvedType_2 = 'BOOLEAN' | 'FLOAT' | 'STRING' | 'COLOR';
-
-declare type UpdateVariableArgs = {
-    variableId: string;
-    payload: UpdateVariablePayload_2;
-};
-
-/**
- * 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>
-}
-
-/**
- * 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.
- */
-declare interface UpdateVariablePayload_2 {
-    /** 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_2[];
-    /** 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_2>;
-
-/**
- * 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_2>;
-
-/**
- * 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 '@figma-vars/hooks';
- *
- * 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_3<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 '@figma-vars/hooks';
- *
- * 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_2;
-
-/**
- * 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>
-}
-
-/**
- * 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.
- */
-declare interface UseVariableModesResult_2 {
-    /** A flat array of all modes across all collections. */
-    modes: VariableMode_2[];
-    /** A map of collection IDs to an array of modes belonging to that collection. */
-    modesByCollectionId: Record<string, VariableMode_2[]>;
-    /** A map of mode IDs to the corresponding mode object for quick lookups. */
-    modesById: Record<string, VariableMode_2>;
-}
-
-/**
- * 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 */
-
-/* Excluded from this release type: VariableAction_2 */
-
-/**
- * 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
-}
-
-/**
- * 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.
- */
-declare interface VariableAlias_2 {
-    /** 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: VariableChange_2 */
-
-/* Excluded from this release type: VariableCollectionChange */
-
-/* Excluded from this release type: VariableCollectionChange_2 */
-
-/**
- * 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
-}
-
-/**
- * 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").
- */
-declare interface VariableMode_2 {
-    /** 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 */
-
-/* Excluded from this release type: VariableModeChange_2 */
-
-/**
- * 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
-}
-
-/**
- * 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.
- */
-declare interface VariableModeValue_2 {
-    /** 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_2;
-}
-
-/**
- * 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 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}
- */
-declare type VariableScope_2 = '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
-
-/**
- * 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}
- */
-declare type VariableValue_2 = string | boolean | number | Color_2 | VariableAlias_2;
-
-export { }