@figma-vars/hooks 1.3.3 → 1.4.3

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

@@ -0,0 +1,53 @@
+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 {};

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

@@ -0,0 +1,40 @@
+import { UpdateVariableArgs } from '../types/hooks';
+/**
+ * React hook that updates a Figma variable by its ID via 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}
+ *
+ * @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',
+ *       },
+ *     });
+ *   };
+ *
+ *   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>;
+ *
+ *   return <button onClick={handleUpdate}>Update Variable</button>;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare const useUpdateVariable: () => import('..').MutationResult<any, UpdateVariableArgs>;

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

@@ -0,0 +1,35 @@
+import { FigmaCollection } from 'types';
+/**
+ * React hook that extracts and memoizes all variable collections from loaded Figma variables data.
+ *
+ * @remarks
+ * Returns an object with:
+ * - `collections`: an array of all variable collections
+ * - `collectionsById`: a lookup table mapping collection IDs to FigmaCollection objects
+ * Useful for building UI pickers, mapping, and variable management tools.
+ *
+ * Call this hook anywhere you need fast, up-to-date access to collections for the current file context.
+ *
+ * @example
+ * ```tsx
+ * import { useVariableCollections } from '@figma-vars/hooks';
+ *
+ * function CollectionList() {
+ *   const { collections } = useVariableCollections();
+ *   if (!collections.length) return <div>No collections found.</div>;
+ *   return (
+ *     <ul>
+ *       {collections.map(col => (
+ *         <li key={col.id}>{col.name}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare const useVariableCollections: () => {
+    collections: FigmaCollection[];
+    collectionsById: Record<string, FigmaCollection>;
+};

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

@@ -0,0 +1,32 @@
+import { UseVariableModesResult } from '../types/hooks';
+/**
+ * React hook that extracts and memoizes all variable modes from loaded Figma variables data.
+ *
+ * @remarks
+ * Returns an object with:
+ * - `modes`: an array of all modes
+ * - `modesByCollectionId`: a lookup table mapping collection IDs to arrays of modes
+ * - `modesById`: a lookup table mapping mode IDs to VariableMode objects
+ *
+ * Useful for building UI pickers, mapping, advanced theme controls, or custom variable management tools. Call this hook anywhere you need fast, up-to-date access to modes for the current file context.
+ *
+ * @example
+ * ```tsx
+ * import { useVariableModes } from '@figma-vars/hooks';
+ *
+ * function ModeList() {
+ *   const { modes } = useVariableModes();
+ *   if (!modes.length) return <div>No modes found.</div>;
+ *   return (
+ *     <ul>
+ *       {modes.map(mode => (
+ *         <li key={mode.modeId}>{mode.name}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare const useVariableModes: () => UseVariableModesResult;

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

@@ -0,0 +1,32 @@
+import { SWRResponse } from 'swr';
+import { LocalVariablesResponse } from 'types';
+/**
+ * React hook that fetches all local variables, collections, and modes for the current Figma file via the Variables API.
+ *
+ * @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)
+ *
+ * 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>;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare const useVariables: () => SWRResponse<LocalVariablesResponse>;

package/dist/src/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @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';

package/dist/src/types/contexts.d.ts

@@ -0,0 +1,77 @@
+import { ReactNode } from 'react';
+/**
+ * Central context shape for FigmaVars—provides authentication and file context to all hooks and consumers in the tree.
+ *
+ * @remarks
+ * - `token`: Figma Personal Access Token (PAT) for authenticating Figma REST API requests. You can generate a PAT in your Figma account settings (https://www.figma.com/developers/api#access-tokens).
+ * - `fileKey`: Figma file key uniquely identifying the current Figma file context. You can find the file key in the Figma file URL—it is the string after `/file/` and before the next `/` (e.g., https://www.figma.com/file/<fileKey>/...).
+ *
+ * This type defines the single source of truth for authentication and file context, available via the FigmaVarsProvider context and typically accessed using `useFigmaTokenContext`.
+ * All variable, collection, and mode hooks rely on this context to determine scope and authorization.
+ *
+ * @example
+ * ```tsx
+ * import { useFigmaTokenContext } from '@figma-vars/hooks';
+ *
+ * function TokenStatus() {
+ *   const { token, fileKey } = useFigmaTokenContext();
+ *   if (!token) return <div>Figma API token missing.</div>;
+ *   return <div>
+ *     <div>Token: {token.slice(0, 4)}... (hidden)</div>
+ *     <div>File key: {fileKey}</div>
+ *   </div>;
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface FigmaTokenContextType {
+    /**
+     * Figma Personal Access Token (PAT), or null if not set. Required for all authenticated Figma REST API operations.
+     * Generate a PAT in Figma account settings: https://www.figma.com/developers/api#access-tokens
+     */
+    token: string | null;
+    /**
+     * Figma file key for the current file context, or null if not set.
+     * The file key is the string after '/file/' in a Figma file URL (e.g., https://www.figma.com/file/<fileKey>/...).
+     */
+    fileKey: string | null;
+}
+/**
+ * Props for the FigmaVarsProvider component, which injects Figma API authentication and file scoping for all descendant hooks and utilities.
+ *
+ * @remarks
+ * - `children`: React nodes to render within the provider—this wraps your app, feature, or test tree.
+ * - `token`: Figma Personal Access Token (PAT) for authenticating API calls. Obtain one in your Figma account settings: https://www.figma.com/developers/api#access-tokens
+ * - `fileKey`: Figma file key identifying the file to scope all variable/collection operations to. Extract the file key from your Figma file URL: https://www.figma.com/file/<fileKey>/...
+ *
+ * Use this to wrap your application, dashboard, or Storybook preview, ensuring all consumers have access to the proper Figma API context and authentication.
+ *
+ * @example
+ * ```tsx
+ * import { FigmaVarsProvider } from '@figma-vars/hooks';
+ *
+ * // At the root of your app:
+ * <FigmaVarsProvider token={myToken} fileKey={myFileKey}>
+ *   <App />
+ * </FigmaVarsProvider>
+ * ```
+ *
+ * @public
+ */
+export interface FigmaVarsProviderProps {
+    /**
+     * The React nodes to render inside the provider.
+     */
+    children: ReactNode;
+    /**
+     * Figma Personal Access Token (PAT) to inject into context. Required for all authenticated API operations.
+     * Generate your PAT in Figma account settings: https://www.figma.com/developers/api#access-tokens
+     */
+    token: string | null;
+    /**
+     * Figma file key (ID) to provide context for all variable and collection operations.
+     * The file key is found in the Figma file URL, after `/file/` and before the next `/` (e.g., https://www.figma.com/file/<fileKey>/...).
+     */
+    fileKey: string | null;
+}

package/dist/src/types/figma.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Enum of supported variable value types in Figma.
+ *
+ * @remarks
+ * Used as the `resolvedType` for Figma variables—defines if the value is a boolean, float, string, or color.
+ *
+ * @example
+ * ```ts
+ * const type: ResolvedType = 'COLOR'
+ * ```
+ *
+ * @public
+ */
+export type ResolvedType = 'BOOLEAN' | 'FLOAT' | 'STRING' | 'COLOR';
+/**
+ * Enum of all valid Figma variable scopes.
+ *
+ * @remarks
+ * Scopes define where a variable can be referenced or applied (e.g., fills, text content, opacity, effects).
+ * Use this to restrict variables to certain design properties in the Figma UI or API.
+ *
+ * @example
+ * ```ts
+ * const scopes: VariableScope[] = ['ALL_FILLS', 'TEXT_CONTENT']
+ * ```
+ *
+ * @public
+ */
+export 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';
+/**
+ * RGBA color value used by Figma variables of type COLOR.
+ *
+ * @remarks
+ * Each component is a float between 0 and 1 (inclusive), matching the Figma API spec.
+ * Used for color values in variable payloads and responses.
+ *
+ * @example
+ * ```ts
+ * const color: Color = { r: 0.5, g: 0.8, b: 0.2, a: 1 }
+ * ```
+ *
+ * @public
+ */
+export interface Color {
+    /** Red channel, 0–1 */
+    r: number;
+    /** Green channel, 0–1 */
+    g: number;
+    /** Blue channel, 0–1 */
+    b: number;
+    /** Alpha channel, 0–1 (opacity) */
+    a: number;
+}
+/**
+ * Value representing a variable alias reference in Figma.
+ *
+ * @remarks
+ * Used when a variable references another variable via aliasing. Type should always be 'VARIABLE_ALIAS'.
+ *
+ * @example
+ * ```ts
+ * const alias: VariableAlias = { type: 'VARIABLE_ALIAS', id: 'VariableID:123:456' }
+ * ```
+ *
+ * @public
+ */
+export interface VariableAlias {
+    /** Type identifier for variable alias objects. Always 'VARIABLE_ALIAS'. */
+    type: 'VARIABLE_ALIAS';
+    /** The referenced variable's Figma variable ID. */
+    id: string;
+}
+/**
+ * Union of all supported Figma variable value types.
+ *
+ * - string, boolean, number, Color, or VariableAlias
+ *
+ * Used in payloads and responses for Figma variable APIs.
+ *
+ * @public
+ */
+export type VariableValue = string | boolean | number | Color | VariableAlias;
+/**
+ * Model of a single Figma variable, including metadata, values by mode, and collection info.
+ *
+ * @remarks
+ * Core unit for all Figma variable APIs. Includes value definitions, metadata, type info, and publishing flags. Variables are always associated with a collection and may have different values per mode.
+ *
+ * @property id - Unique Figma variable ID
+ * @property name - Human-readable variable name
+ * @property variableCollectionId - Parent collection ID
+ * @property resolvedType - Data type for this variable (BOOLEAN, FLOAT, STRING, or COLOR)
+ * @property valuesByMode - Map of mode IDs to variable values (by type)
+ * @property description - Optional freeform description
+ * @property hiddenFromPublishing - If true, this variable is hidden from publishing
+ * @property scopes - Array of allowed or assigned Figma variable scopes
+ * @property codeSyntax - Map of language IDs to code sample strings for this variable
+ * @property updatedAt - ISO8601 timestamp of last update
+ *
+ * @example
+ * ```ts
+ * const variable: FigmaVariable = {
+ *   id: 'VariableID:123:456',
+ *   name: 'Primary Color',
+ *   variableCollectionId: 'VariableCollectionId:789:012',
+ *   resolvedType: 'COLOR',
+ *   valuesByMode: { 'MODE:dark': { r: 0, g: 0, b: 0, a: 1 } },
+ *   description: 'Main brand color',
+ *   hiddenFromPublishing: false,
+ *   scopes: ['ALL_FILLS'],
+ *   codeSyntax: { css: 'var(--primary-color)' },
+ *   updatedAt: '2024-06-21T23:59:59Z',
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface FigmaVariable {
+    id: string;
+    name: string;
+    variableCollectionId: string;
+    resolvedType: ResolvedType;
+    valuesByMode: Record<string, VariableValue>;
+    description: string;
+    hiddenFromPublishing: boolean;
+    scopes: VariableScope[];
+    codeSyntax: Record<string, string>;
+    updatedAt: string;
+}
+/**
+ * Model of a Figma variable mode (e.g., Light, Dark, Custom).
+ *
+ * @remarks
+ * Modes are used to provide variable overrides for different states (themes, breakpoints, etc.).
+ * Each collection may define its own set of modes.
+ *
+ * @example
+ * ```ts
+ * const mode: VariableMode = { modeId: 'MODE:dark', name: 'Dark' }
+ * ```
+ *
+ * @public
+ */
+export interface VariableMode {
+    /** Unique mode ID */
+    modeId: string;
+    /** Human-readable mode name */
+    name: string;
+}
+/**
+ * Model of a Figma variable collection (grouping of related variables and modes).
+ *
+ * @remarks
+ * Collections define shared settings, available modes, and membership of variables. Used as the organizing tier for all variable operations.
+ *
+ * @property id - Unique Figma collection ID
+ * @property name - Human-readable collection name
+ * @property modes - List of VariableMode objects
+ * @property defaultModeId - The default mode for this collection
+ * @property variableIds - Array of IDs of variables in this collection
+ * @property hiddenFromPublishing - If true, collection is hidden from publishing
+ * @property updatedAt - ISO8601 timestamp of last update
+ *
+ * @example
+ * ```ts
+ * const collection: FigmaCollection = {
+ *   id: 'VariableCollectionId:789:012',
+ *   name: 'Theme Colors',
+ *   modes: [{ modeId: 'MODE:dark', name: 'Dark' }],
+ *   defaultModeId: 'MODE:dark',
+ *   variableIds: ['VariableID:123:456'],
+ *   hiddenFromPublishing: false,
+ *   updatedAt: '2024-06-21T23:59:59Z',
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface FigmaCollection {
+    id: string;
+    name: string;
+    modes: VariableMode[];
+    defaultModeId: string;
+    variableIds: string[];
+    hiddenFromPublishing: boolean;
+    updatedAt: string;
+}
+/**
+ * API response shape for the Figma Variables API local variables endpoint.
+ *
+ * @remarks
+ * Contains all collections and variables available in the current Figma file context.
+ * Use this as the source of truth for fetching and mapping Figma variable data.
+ *
+ * @property meta - Metadata object containing collections and variables.
+ * @property meta.variableCollections - Map of collection IDs to FigmaCollection objects.
+ * @property meta.variables - Map of variable IDs to FigmaVariable objects.
+ *
+ * @example
+ * ```ts
+ * import type { LocalVariablesResponse } from '@figma-vars/hooks';
+ *
+ * function handleResponse(response: LocalVariablesResponse) {
+ *   const collections = Object.values(response.meta.variableCollections);
+ *   const variables = Object.values(response.meta.variables);
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface LocalVariablesResponse {
+    meta: {
+        /** Map of collection IDs to FigmaCollection objects. */
+        variableCollections: Record<string, FigmaCollection>;
+        /** Map of variable IDs to FigmaVariable objects. */
+        variables: Record<string, FigmaVariable>;
+    };
+}
+/**
+ * Standard error response shape for Figma API error objects.
+ *
+ * @remarks
+ * Returned by API calls when an error occurs (e.g., invalid token, not found, etc.).
+ *
+ * @property statusCode - HTTP status code returned by the Figma API.
+ * @property message - Human-readable error message describing the failure.
+ *
+ * @example
+ * ```ts
+ * import type { FigmaError } from '@figma-vars/hooks';
+ *
+ * function handleError(error: FigmaError) {
+ *   console.error(error.statusCode, error.message);
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface FigmaError {
+    /** HTTP status code returned by the Figma API. */
+    statusCode: number;
+    /** Human-readable error message describing the failure. */
+    message: string;
+}

package/dist/src/types/hooks.d.ts

@@ -0,0 +1,67 @@
+import { VariableMode } from './figma';
+import { UpdateVariablePayload } from './mutations';
+/**
+ * Arguments for updating a Figma variable via the useUpdateVariable hook.
+ *
+ * @remarks
+ * Use with the useUpdateVariable hook to specify which Figma variable to update and the properties to set. This enables fine-grained updates for custom UIs, bulk editors, and automation tools.
+ *
+ * @property variableId - The unique Figma variable ID to update. This can be found in variable metadata or Figma plugin dev tools.
+ * @property payload - The payload object with one or more variable properties to update (e.g., name, description, valuesByMode).
+ *
+ * @example
+ * ```ts
+ * import type { UpdateVariableArgs } from '@figma-vars/hooks';
+ *
+ * const args: UpdateVariableArgs = {
+ *   variableId: 'VariableID:123:456',
+ *   payload: { name: 'Updated Name', description: 'Updated description' }
+ * };
+ * // Pass to mutate(): mutate(args)
+ * ```
+ *
+ * @public
+ */
+export interface UpdateVariableArgs {
+    /** The unique Figma variable ID to update. */
+    variableId: string;
+    /** The payload object with updated properties for the variable. */
+    payload: UpdateVariablePayload;
+}
+/**
+ * Return value of the useVariableModes hook—provides all variable modes and lookup tables for the current Figma file context.
+ *
+ * @remarks
+ * Returned by useVariableModes. Use this to quickly map modes by ID, by collection, or as a flat array for UI display, theming, and conditional logic.
+ *
+ * @property modes - Flat array of all VariableMode objects in the file.
+ * @property modesByCollectionId - Lookup map of collection IDs to arrays of VariableMode objects (for grouping modes by collection).
+ * @property modesById - Lookup map of mode IDs to VariableMode objects (for fast direct access).
+ *
+ * @example
+ * ```ts
+ * import { useVariableModes } from '@figma-vars/hooks';
+ *
+ * function ThemeSwitcher() {
+ *   const { modes, modesById } = useVariableModes();
+ *   // Build UI for switching themes based on mode names
+ *   return (
+ *     <select>
+ *       {modes.map(mode => (
+ *         <option key={mode.modeId} value={mode.modeId}>{mode.name}</option>
+ *       ))}
+ *     </select>
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface UseVariableModesResult {
+    /** Flat array of all VariableMode objects in the file. */
+    modes: VariableMode[];
+    /** Lookup map of collection IDs to arrays of VariableMode objects. */
+    modesByCollectionId: Record<string, VariableMode[]>;
+    /** Lookup map of mode IDs to VariableMode objects. */
+    modesById: Record<string, VariableMode>;
+}