@figma-vars/hooks 1.2.0 → 1.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figma-vars/hooks",
-  "version": "1.2.0",
+  "version": "1.3.2",
   "description": "Typed React hooks for managing Figma Variables, modes, tokens, and bindings via API.",
   "author": "Mark Learst",
   "license": "MIT",
@@ -36,8 +36,8 @@
     "node": ">=18.0.0"
   },
   "peerDependencies": {
-    "react": ">=19.0.0",
-    "react-dom": ">=19.0.0"
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
   },
   "sideEffects": false,
   "exports": {
@@ -52,14 +52,21 @@
     "url": "https://github.com/sponsors/marklearst"
   },
   "devDependencies": {
-    "@types/react": "^19.1.8",
-    "@types/react-dom": "^19.1.6",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^24.0.3",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.5.2",
+    "@vitest/coverage-v8": "^2.0.5",
+    "jsdom": "^26.1.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "typescript": "~5.8.3",
     "vite": "^6.3.5",
     "vite-plugin-dts": "^4.5.4",
-    "vite-tsconfig-paths": "^5.1.4"
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^2.0.5"
   },
   "directories": {
     "doc": "docs"
@@ -70,7 +77,9 @@
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "preview": "vite preview",
+    "test": "vitest",
     "postversion": "git push && git push --tags"
   }
 }

package/dist/constants/index.d.ts

@@ -1,3 +0,0 @@
-export declare const FIGMA_API_BASE_URL = "https://api.figma.com";
-export declare const FIGMA_FILES_ENDPOINT = "https://api.figma.com/v1/files";
-export declare const FIGMA_VARIABLES_ENDPOINT: (fileKey: string) => string;

package/dist/contexts/FigmaTokenContext.d.ts

@@ -1,49 +0,0 @@
-import { ReactNode } from 'react';
-/**
- * @internal
- * The shape of the context provided by `FigmaVarsProvider`.
- */
-interface FigmaTokenContextType {
-    /** The Figma Personal Access Token. */
-    token: string | null;
-    /** The key of the Figma file to access. */
-    fileKey: string | null;
-}
-/**
- * Props for the `FigmaVarsProvider` component.
- */
-interface FigmaVarsProviderProps {
-    /** The React children to render within the provider. */
-    children: ReactNode;
-    /** The Figma Personal Access Token. Can be sourced from anywhere (e.g., env variables, localStorage). */
-    token: string | null;
-    /** The key of the Figma file to be accessed by the hooks. */
-    fileKey: string | null;
-}
-/**
- * A React Context Provider that makes the Figma token and file key available to all `figma-vars-hooks`.
- * Wrap your application or component tree with this provider.
- *
- * @example
- * ```tsx
- * import { FigmaVarsProvider } from '@figma-vars/hooks';
- *
- * const App = () => (
- *   <FigmaVarsProvider
- *     token="your-figma-token"
- *     fileKey="your-figma-file-key"
- *   >
- *     <YourComponentThatUsesTheHooks />
- *   </FigmaVarsProvider>
- * );
- * ```
- */
-export declare const FigmaVarsProvider: ({ children, token, fileKey, }: FigmaVarsProviderProps) => import("react/jsx-runtime").JSX.Element;
-/**
- * @internal
- * A hook to access the Figma token and file key from the context.
- * Throws an error if used outside of a `FigmaVarsProvider`.
- * @returns The Figma token and file key.
- */
-export declare const useFigmaTokenContext: () => FigmaTokenContextType;
-export {};

package/dist/hooks/useFigmaToken.d.ts

@@ -1,17 +0,0 @@
-/**
- * Retrieves the Figma API token from the FigmaVarsProvider.
- * This hook must be used within a component wrapped by FigmaVarsProvider.
- *
- * @returns The Figma Personal Access Token, or `null` if it has not been provided.
- *
- * @example
- * ```tsx
- * const MyComponent = () => {
- *   const figmaToken = useFigmaToken();
- *   // Now you can use the token for manual API calls if needed.
- *   return <div>...</div>;
- * };
- * ```
- */
-declare const useFigmaToken: () => string | null;
-export default useFigmaToken;

package/dist/hooks/useVariableCollections.d.ts

@@ -1,26 +0,0 @@
-import { FigmaCollection } from 'types';
-/**
- * A convenience hook to access the variable collections from the data fetched by `useVariables`.
- * This hook does not perform its own data fetching; it's a lightweight selector on the main data source.
- *
- * It's recommended to use this hook when you only need collection data to avoid re-rendering components unnecessarily when other parts of the Figma data change.
- *
- * @returns An object containing the collections as an array (`collections`) and as a map by ID (`collectionsById`).
- *
- * @example
- * ```tsx
- * const { collections } = useVariableCollections();
- *
- * return (
- *   <ul>
- *     {collections.map(collection => (
- *       <li key={collection.id}>{collection.name}</li>
- *     ))}
- *   </ul>
- * );
- * ```
- */
-export declare const useVariableCollections: () => {
-    collections: FigmaCollection[];
-    collectionsById: Record<string, FigmaCollection>;
-};

package/dist/hooks/useVariableModes.d.ts

@@ -1,16 +0,0 @@
-import { UseVariableModesResult } from '../types/hooks';
-/**
- * A convenience hook to access and process variable modes from the data fetched by `useVariables`.
- * This hook does not perform its own data fetching; it's a lightweight selector that memoizes the processed mode data.
- *
- * Use this hook when you need mode data, structured for easy access.
- *
- * @returns An object containing all modes as an array (`modes`), modes grouped by collection ID (`modesByCollectionId`), and modes indexed by their own ID (`modesById`).
- *
- * @example
- * ```tsx
- * const { modesById } = useVariableModes();
- * const lightMode = modesById['mode-123'];
- * ```
- */
-export declare const useVariableModes: () => UseVariableModesResult;

package/dist/hooks/useVariables.d.ts

@@ -1,25 +0,0 @@
-import { LocalVariablesResponse } from 'types';
-/**
- * The primary hook for fetching all local variables, collections, and modes for the file specified in the `FigmaVarsProvider`.
- * This hook serves as the foundation for other data hooks like `useVariableCollections` and `useVariableModes`.
- *
- * It uses `swr` for efficient data fetching, caching, and revalidation.
- *
- * @returns An object containing the raw API response (`data`), loading state (`isLoading`), validation state (`isValidating`), and any errors (`error`).
- *
- * @example
- * ```tsx
- * const { data, isLoading, error } = useVariables();
- *
- * if (isLoading) return <div>Loading...</div>;
- * if (error) return <div>Error: {error.message}</div>;
- *
- * const collections = Object.values(data?.meta.variableCollections ?? {});
- * ```
- */
-export declare const useVariables: () => {
-    data: LocalVariablesResponse | undefined;
-    isLoading: boolean;
-    isValidating: boolean;
-    error: any;
-};

package/dist/mutations/bulkUpdateVariables.d.ts

@@ -1,25 +0,0 @@
-import { BulkUpdatePayload } from '../types/mutations';
-/**
- * Performs a bulk update of variables in a Figma file.
- * This endpoint can be used to create, update, or delete multiple variables in a single API call.
- *
- * @param token - The Figma Personal Access Token.
- * @param fileKey - The key of the Figma file where the variables reside.
- * @param payload - The bulk update payload, containing arrays of variables to create, update, and/or delete.
- * @returns A promise that resolves with the metadata from the Figma API about the bulk operation.
- * @throws Will throw an error if the fetch call fails or if the API returns an error response.
- *
- * @example
- * ```ts
- * const payload = {
- *   create: [{ name: "new-var", variableCollectionId: "VC:1:1", resolvedType: "FLOAT" }],
- *   update: [{ id: "VariableID:123:456", name: "updated-name" }],
- *   delete: ["VariableID:789:101"]
- * };
- *
- * bulkUpdateVariables("your-token", "your-file-key", payload)
- *   .then(response => console.log("Bulk update successful:", response))
- *   .catch(error => console.error(error));
- * ```
- */
-export declare const bulkUpdateVariables: (token: string, fileKey: string, payload: BulkUpdatePayload) => Promise<any>;

package/dist/mutations/createVariable.d.ts

@@ -1,26 +0,0 @@
-import { CreateVariablePayload } from '../types/mutations';
-/**
- * Creates a new variable in a Figma file.
- *
- * This function sends a POST request to the Figma API to create a new variable.
- * It requires a valid Figma token with `file_variables:write` scope.
- *
- * @param token - The Figma Personal Access Token.
- * @param payload - The data for the new variable, including its name, collection ID, and type.
- * @returns A promise that resolves with the created variable data from the Figma API.
- * @throws Will throw an error if the fetch call fails or if the API returns an error response.
- *
- * @example
- * ```ts
- * const newVariableData = {
- *   name: "new-color",
- *   variableCollectionId: "VariableCollectionId:1:1",
- *   resolvedType: "COLOR"
- * };
- *
- * createVariable("your-figma-token", newVariableData)
- *   .then(result => console.log("Variable created:", result))
- *   .catch(error => console.error(error));
- * ```
- */
-export declare const createVariable: (token: string, payload: CreateVariablePayload) => Promise<any>;

package/dist/mutations/deleteVariable.d.ts

@@ -1,19 +0,0 @@
-/**
- * Deletes a variable from a Figma file.
- *
- * This function sends a DELETE request to the Figma API to remove a single variable.
- * It requires a valid Figma token with `file_variables:write` scope.
- *
- * @param token - The Figma Personal Access Token.
- * @param variableId - The ID of the variable to delete.
- * @returns A promise that resolves when the variable has been successfully deleted. The Figma API returns no content on a successful DELETE.
- * @throws Will throw an error if the fetch call fails or if the API returns an error response.
- *
- * @example
- * ```ts
- * deleteVariable("your-figma-token", "VariableID:1:1")
- *   .then(() => console.log("Variable deleted successfully"))
- *   .catch(error => console.error(error));
- * ```
- */
-export declare const deleteVariable: (token: string, variableId: string) => Promise<void>;

package/dist/mutations/updateVariable.d.ts

@@ -1,26 +0,0 @@
-import { UpdateVariablePayload } from '../types/mutations';
-/**
- * Updates an existing variable in a Figma file.
- *
- * This function sends a PUT request to the Figma API to modify a single variable.
- * It requires a valid Figma token with `file_variables:write` scope.
- *
- * @param token - The Figma Personal Access Token.
- * @param variableId - The ID of the variable to update.
- * @param payload - The data to update for the variable.
- * @returns A promise that resolves when the variable has been successfully updated. The Figma API returns no content on a successful PUT.
- * @throws Will throw an error if the fetch call fails or if the API returns an error response.
- *
- * @example
- * ```ts
- * const updatedData = {
- *   name: "new-color-name",
- *   description: "An updated description"
- * };
- *
- * updateVariable("your-figma-token", "VariableID:1:1", updatedData)
- *   .then(() => console.log("Variable updated successfully"))
- *   .catch(error => console.error(error));
- * ```
- */
-export declare const updateVariable: (token: string, variableId: string, payload: UpdateVariablePayload) => Promise<void>;

package/dist/types/figma.d.ts

@@ -1,111 +0,0 @@
-/**
- * The resolved type of a Figma variable.
- */
-export type ResolvedType = 'BOOLEAN' | 'FLOAT' | 'STRING' | '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.
- */
-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';
-/**
- * Represents a color in RGBA format.
- */
-export 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 an alias to another Figma variable.
- * This is used when a variable's value is set to reference another variable.
- */
-export 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;
-}
-/**
- * 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.
- */
-export type VariableValue = string | boolean | number | Color | VariableAlias;
-/**
- * Represents a single Figma variable.
- */
-export 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;
-}
-/**
- * Represents a single mode within a variable collection.
- */
-export interface VariableMode {
-    /** The unique identifier for the mode. */
-    modeId: string;
-    /** The name of the mode (e.g., "Light", "Dark"). */
-    name: string;
-}
-/**
- * Represents a collection of Figma variables, which can contain multiple modes.
- */
-export 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;
-}
-/**
- * The structure of the successful response from the Figma API's `/v1/files/{file_key}/variables/local` endpoint.
- */
-export 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>;
-    };
-}
-/**
- * A generic error shape for failed Figma API requests.
- */
-export interface FigmaError {
-    /** The HTTP status code of the error. */
-    statusCode: number;
-    /** The error message from the API. */
-    message: string;
-}

package/dist/types/hooks.d.ts

@@ -1,12 +0,0 @@
-import { VariableMode } from './figma';
-/**
- * The return type for the `useVariableModes` hook.
- */
-export 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>;
-}

package/dist/types/index.d.ts

@@ -1,3 +0,0 @@
-export * from './figma';
-export * from './hooks';
-export * from './mutations';

package/dist/types/mutations.d.ts

@@ -1,114 +0,0 @@
-import { ResolvedType, VariableScope, VariableValue } from './figma';
-/**
- * The payload for the `createVariable` function.
- * Defines the properties for a new variable.
- */
-export 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 `updateVariable` function.
- * All properties are optional.
- */
-export 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 action to perform in a bulk update.
- * @internal
- */
-export type VariableAction = 'CREATE' | 'UPDATE' | 'DELETE';
-/**
- * A change to a variable collection in a bulk update.
- * @internal
- */
-export interface VariableCollectionChange {
-    action: VariableAction;
-    id: string;
-    name?: string;
-    initialModeId?: string;
-    hiddenFromPublishing?: boolean;
-}
-/**
- * A change to a variable mode in a bulk update.
- * @internal
- */
-export interface VariableModeChange {
-    action: VariableAction;
-    id: string;
-    name?: string;
-    variableCollectionId: string;
-}
-/**
- * A change to a variable's properties in a bulk update.
- * @internal
- */
-export interface VariableChange {
-    action: VariableAction;
-    id: string;
-    name?: string;
-    variableCollectionId?: string;
-    resolvedType?: ResolvedType;
-    description?: string;
-    hiddenFromPublishing?: boolean;
-    scopes?: VariableScope[];
-    codeSyntax?: Record<string, string>;
-}
-/**
- * A change to a variable's value in a specific mode in a bulk update.
- */
-export 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 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.
- */
-export 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[];
-}
-export interface BulkUpdateResponse {
-    error: boolean;
-    status: number;
-    message?: string;
-    meta?: {
-        tempIdToRealId: Record<string, string>;
-    };
-}

package/dist/utils/fetcher.d.ts

@@ -1,13 +0,0 @@
-/**
- * @internal
- * A generic fetcher function designed to work with SWR.
- * It takes a URL and a Figma token, and returns the JSON response.
- *
- * This function is used by the data-fetching hooks to make authenticated requests to the Figma API.
- *
- * @param url - The API endpoint to fetch.
- * @param token - The Figma Personal Access Token.
- * @returns A promise that resolves with the JSON data from the API.
- * @throws Will throw an error if the fetch call fails or if the API returns an error response.
- */
-export declare const fetcher: (url: string, token: string) => Promise<any>;

package/dist/utils/filterVariables.d.ts

@@ -1,31 +0,0 @@
-import { FigmaVariable, ResolvedType } from 'types';
-/**
- * Filters an array of Figma variables based on specified criteria.
- * This utility can filter by variable type, a partial name match, or both.
- *
- * @param variables - The array of `FigmaVariable` objects to filter.
- * @param criteria - An object specifying the filter criteria.
- * @param criteria.resolvedType - The variable type (e.g., 'COLOR', 'FLOAT') to filter by.
- * @param criteria.name - A string to search for within the variable names (case-sensitive).
- * @returns A new array containing only the variables that match the criteria.
- *
- * @example
- * ```ts
- * import { filterVariables } from 'utils/filterVariables';
- *
- * const allVariables = [
- *   { name: 'primary-color', resolvedType: 'COLOR', ... },
- *   { name: 'font-size-large', resolvedType: 'FLOAT', ... }
- * ];
- *
- * // Filter by type
- * const colorVariables = filterVariables(allVariables, { resolvedType: 'COLOR' });
- *
- * // Filter by name
- * const fontVariables = filterVariables(allVariables, { name: 'font' });
- * ```
- */
-export declare function filterVariables(variables: FigmaVariable[], criteria: {
-    resolvedType?: ResolvedType;
-    name?: string;
-}): FigmaVariable[];