@figma-vars/hooks 1.1.0 → 1.2.0

package/dist/types/mutations.d.ts

@@ -1,36 +1,49 @@
-import { FigmaVariable, ResolvedType, VariableScope, VariableValue } from './figma';
-export interface FigmaOperationResponse {
-    success: boolean;
-    message?: string;
-}
-export interface VariableValueUpdate {
-    modeId: string;
-    value: string;
-}
-export type SpecificType = VariableValueUpdate[];
+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>;
 }
-export interface VariableActionResponse {
-    error: boolean;
-    status: number;
-    message?: string;
-    variable?: FigmaVariable;
-}
+/**
+ * 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;
@@ -38,12 +51,20 @@ export interface VariableCollectionChange {
     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;
@@ -55,15 +76,32 @@ export interface VariableChange {
     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 {

package/dist/utils/fetcher.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @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,4 +1,30 @@
 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figma-vars/hooks",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Typed React hooks for managing Figma Variables, modes, tokens, and bindings via API.",
   "author": "Mark Learst",
   "license": "MIT",

package/dist/utils/authHelpers.d.ts

@@ -1,4 +0,0 @@
-/**
- * Retrieves the Figma API token from environment variables or any other secure storage mechanism you've implemented.
- */
-export declare const getFigmaToken: () => string | null;

package/dist/utils/fetchHelpers.d.ts

@@ -1,10 +0,0 @@
-interface FetchOptions {
-    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
-    body?: BodyInit | null;
-    headers?: HeadersInit;
-}
-/**
- * A helper function for making authenticated fetch requests to the Figma API.
- */
-export declare const fetchWithAuth: (url: string, options?: FetchOptions) => Promise<any>;
-export {};