@figma-vars/hooks 1.3.3 → 1.4.3

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

@@ -0,0 +1,30 @@
+/****
+ * @packageDocumentation
+ *
+ * OSS barrel file for all public types and interfaces in @figma-vars/hooks.
+ *
+ * @remarks
+ * This module re-exports all Figma domain types (variables, collections, modes, API response models), mutation argument/result types, and all context/provider types for robust type-safe integration. Import types directly from this barrel for application code, plugins, API adapters, or custom UI tooling. All official Figma variable, mutation, and provider types are available from this entry point—see below for usage.
+ *
+ * @example
+ * ```ts
+ * // Importing multiple types for advanced integration and custom hooks:
+ * import type {
+ *   FigmaVariable,
+ *   FigmaCollection,
+ *   VariableMode,
+ *   UpdateVariableArgs,
+ *   FigmaVarsProviderProps,
+ *   MutationResult,
+ * } from '@figma-vars/hooks';
+ *
+ * // Use for type-safe props, mutation payloads, and UI mapping:
+ * function MyFeature(props: { variable: FigmaVariable; onUpdate: (args: UpdateVariableArgs) => void }) {
+ *   // ...
+ * }
+ * ```
+ */
+export * from './figma';
+export * from './hooks';
+export * from './mutations';
+export * from './contexts';

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

@@ -0,0 +1,314 @@
+import { ResolvedType, VariableScope, VariableValue } from './figma';
+/**
+ * Payload for creating a new Figma variable in a specific collection.
+ *
+ * @remarks
+ * Use with the `useCreateVariable` hook to specify the properties of the new variable.
+ * Optional fields allow customization of description, publishing visibility, scopes, and code syntax.
+ *
+ * @property name - The human-readable name of the variable.
+ * @property variableCollectionId - The ID of the collection this variable belongs to.
+ * @property resolvedType - The data type of the variable value (e.g., 'COLOR', 'FLOAT').
+ * @property description - Optional description text for documentation or tooling.
+ * @property hiddenFromPublishing - Optional flag to hide the variable from published styles.
+ * @property scopes - Optional list of scopes restricting where the variable can be applied.
+ * @property codeSyntax - Optional mapping of language identifiers to code snippets for this variable.
+ *
+ * @example
+ * ```ts
+ * import type { CreateVariablePayload } from '@figma-vars/hooks';
+ *
+ * const newVariable: CreateVariablePayload = {
+ *   name: 'Primary Color',
+ *   variableCollectionId: 'VariableCollectionId:123:456',
+ *   resolvedType: 'COLOR',
+ *   description: 'Main brand color',
+ *   hiddenFromPublishing: false,
+ *   scopes: ['ALL_FILLS'],
+ *   codeSyntax: { css: 'var(--primary-color)' },
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface CreateVariablePayload {
+    name: string;
+    variableCollectionId: string;
+    resolvedType: ResolvedType;
+    description?: string;
+    hiddenFromPublishing?: boolean;
+    scopes?: VariableScope[];
+    codeSyntax?: Record<string, string>;
+}
+/**
+ * Payload for updating properties of an existing Figma variable.
+ *
+ * @remarks
+ * Use with the `useUpdateVariable` hook to specify fields to update.
+ * All fields are optional, allowing partial updates.
+ *
+ * @property name - New name for the variable.
+ * @property description - New description text.
+ * @property hiddenFromPublishing - Update publishing visibility.
+ * @property scopes - Update scopes.
+ * @property codeSyntax - Update code syntax mapping.
+ *
+ * @example
+ * ```ts
+ * import type { UpdateVariablePayload } from '@figma-vars/hooks';
+ *
+ * const updatePayload: UpdateVariablePayload = {
+ *   name: 'Updated Color Name',
+ *   description: 'Updated description',
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface UpdateVariablePayload {
+    name?: string;
+    description?: string;
+    hiddenFromPublishing?: boolean;
+    scopes?: VariableScope[];
+    codeSyntax?: Record<string, string>;
+}
+/**
+ * Enum of possible mutation actions for variables, collections, or modes.
+ *
+ * @remarks
+ * Used internally and in bulk update payloads to indicate the type of change.
+ *
+ * @public
+ */
+export type VariableAction = 'CREATE' | 'UPDATE' | 'DELETE';
+/**
+ * Represents a change operation on a Figma variable collection.
+ *
+ * @remarks
+ * Use in bulk update payloads to create, update, or delete collections.
+ *
+ * @property action - The mutation action to perform.
+ * @property id - Unique ID of the collection affected.
+ * @property name - Optional new name for the collection.
+ * @property initialModeId - Optional mode to set as default for the collection.
+ * @property hiddenFromPublishing - Optional flag to update publishing visibility.
+ *
+ * @example
+ * ```ts
+ * import type { VariableCollectionChange } from '@figma-vars/hooks';
+ *
+ * const change: VariableCollectionChange = {
+ *   action: 'UPDATE',
+ *   id: 'VariableCollectionId:123:456',
+ *   name: 'New Collection Name',
+ *   initialModeId: 'MODE:dark',
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface VariableCollectionChange {
+    action: VariableAction;
+    id: string;
+    name?: string;
+    initialModeId?: string;
+    hiddenFromPublishing?: boolean;
+}
+/**
+ * Represents a change operation on a Figma variable mode.
+ *
+ * @remarks
+ * Use in bulk update payloads to create, update, or delete modes.
+ *
+ * @property action - The mutation action to perform.
+ * @property id - Unique ID of the mode affected.
+ * @property name - Optional new name for the mode.
+ * @property variableCollectionId - The ID of the collection this mode belongs to.
+ *
+ * @example
+ * ```ts
+ * import type { VariableModeChange } from '@figma-vars/hooks';
+ *
+ * const modeChange: VariableModeChange = {
+ *   action: 'CREATE',
+ *   id: 'MODE:light',
+ *   name: 'Light Mode',
+ *   variableCollectionId: 'VariableCollectionId:123:456',
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface VariableModeChange {
+    action: VariableAction;
+    id: string;
+    name?: string;
+    variableCollectionId: string;
+}
+/**
+ * Represents a change operation on a Figma variable.
+ *
+ * @remarks
+ * Use in bulk update payloads to create, update, or delete variables.
+ *
+ * @property action - The mutation action to perform.
+ * @property id - Unique ID of the variable affected.
+ * @property name - Optional new name for the variable.
+ * @property variableCollectionId - Optional new collection ID for the variable.
+ * @property resolvedType - Optional new data type for the variable.
+ * @property description - Optional new description.
+ * @property hiddenFromPublishing - Optional update to publishing visibility.
+ * @property scopes - Optional update to scopes.
+ * @property codeSyntax - Optional update to code syntax.
+ *
+ * @example
+ * ```ts
+ * import type { VariableChange } from '@figma-vars/hooks';
+ *
+ * const varChange: VariableChange = {
+ *   action: 'DELETE',
+ *   id: 'VariableID:123:456',
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface VariableChange {
+    action: VariableAction;
+    id: string;
+    name?: string;
+    variableCollectionId?: string;
+    resolvedType?: ResolvedType;
+    description?: string;
+    hiddenFromPublishing?: boolean;
+    scopes?: VariableScope[];
+    codeSyntax?: Record<string, string>;
+}
+/**
+ * Value assignment for a specific Figma variable in a specific mode.
+ *
+ * @remarks
+ * Used to represent the value of a variable for a given mode in bulk updates and payloads.
+ *
+ * @property variableId - The Figma variable ID being set.
+ * @property modeId - The mode ID (e.g., 'MODE:dark') this value applies to.
+ * @property value - The variable value, which can be a string, number, boolean, Color, or VariableAlias.
+ *
+ * @example
+ * ```ts
+ * import type { VariableModeValue } from '@figma-vars/hooks';
+ *
+ * const modeValue: VariableModeValue = {
+ *   variableId: 'VariableID:123:456',
+ *   modeId: 'MODE:dark',
+ *   value: { r: 0, g: 0, b: 0, a: 1 },
+ * };
+ * ```
+ *
+ * @public
+ */
+export interface VariableModeValue {
+    variableId: string;
+    modeId: string;
+    value: VariableValue;
+}
+/**
+ * Payload for performing a bulk update of Figma variables, collections, modes, and values.
+ *
+ * @remarks
+ * Use with the `useBulkUpdateVariables` hook to perform atomic multi-entity updates.
+ *
+ * @property variableCollections - Optional array of collection changes.
+ * @property variableModes - Optional array of mode changes.
+ * @property variables - Optional array of variable changes.
+ * @property variableModeValues - Optional array of variable-mode value assignments.
+ *
+ * @example
+ * ```ts
+ * import type { BulkUpdatePayload } from '@figma-vars/hooks';
+ *
+ * const payload: BulkUpdatePayload = {
+ *   variableCollections: [{ action: 'UPDATE', id: 'VariableCollectionId:123', name: 'New Name' }],
+ *   variableModes: [{ action: 'CREATE', id: 'MODE:light', name: 'Light', variableCollectionId: 'VariableCollectionId:123' }],
+ *   variables: [{ action: 'DELETE', id: 'VariableID:456' }],
+ *   variableModeValues: [{ variableId: 'VariableID:789', modeId: 'MODE:dark', value: true }],
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface BulkUpdatePayload {
+    variableCollections?: VariableCollectionChange[];
+    variableModes?: VariableModeChange[];
+    variables?: VariableChange[];
+    variableModeValues?: VariableModeValue[];
+}
+/**
+ * Response from bulk update mutation API calls.
+ *
+ * @remarks
+ * Contains status, error indication, and optional mapping of temporary to real IDs.
+ *
+ * @property error - Boolean indicating if an error occurred.
+ * @property status - HTTP status code from the API response.
+ * @property message - Optional human-readable error or status message.
+ * @property meta - Optional metadata including temporary-to-real ID mapping.
+ *
+ * @example
+ * ```ts
+ * import type { BulkUpdateResponse } from '@figma-vars/hooks';
+ *
+ * function handleResponse(response: BulkUpdateResponse) {
+ *   if (response.error) {
+ *     console.error('Update failed:', response.message);
+ *   } else {
+ *     console.log('Update succeeded, IDs:', response.meta?.tempIdToRealId);
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface BulkUpdateResponse {
+    error: boolean;
+    status: number;
+    message?: string;
+    meta?: {
+        tempIdToRealId: Record<string, string>;
+    };
+}
+/**
+ * Generic state shape for mutation hooks.
+ *
+ * @remarks
+ * Tracks mutation lifecycle states (`idle`, `loading`, `success`, `error`), along with data and error info.
+ *
+ * @typeParam TData - The type of data returned by the mutation.
+ *
+ * @public
+ */
+export interface MutationState<TData> {
+    status: 'idle' | 'loading' | 'success' | 'error';
+    data: TData | null;
+    error: Error | null;
+}
+/**
+ * Return value of mutation hooks.
+ *
+ * @remarks
+ * Combines mutation state with a `mutate` trigger function accepting a payload, along with convenient booleans for status.
+ *
+ * @typeParam TData - The type of data returned by the mutation.
+ * @typeParam TPayload - The payload type accepted by the mutation trigger.
+ *
+ * @public
+ */
+export 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;
+}

package/dist/src/utils/filterVariables.d.ts

@@ -0,0 +1,31 @@
+import { FigmaVariable, ResolvedType } from 'types';
+/**
+ * Utility function to filter Figma variables by type and/or substring name match.
+ *
+ * @remarks
+ * Returns a new array of variables matching the provided criteria. Use for building type pickers, variable search, dashboard views, or bulk edit tools. Filtering is case-sensitive for `name`. Pass no criteria to return all variables unfiltered.
+ *
+ * @param variables - The array of FigmaVariable objects to filter.
+ * @param criteria - Object specifying filter fields. Provide a `resolvedType` (e.g., 'COLOR', 'FLOAT') and/or a `name` substring to match variable names.
+ * @returns Array of FigmaVariable objects that match all provided criteria. Returns an empty array if no matches found. Returns all variables if criteria is empty.
+ *
+ * @example
+ * ```ts
+ * import { filterVariables } from '@figma-vars/hooks';
+ *
+ * // Example 1: Filter all color variables
+ * const colorVars = filterVariables(allVars, { resolvedType: 'COLOR' });
+ *
+ * // Example 2: Filter variables containing 'brand' in their name (case-sensitive)
+ * const brandVars = filterVariables(allVars, { name: 'brand' });
+ *
+ * // Example 3: Filter variables that are COLOR and include 'brand' in name
+ * const filtered = filterVariables(allVars, { resolvedType: 'COLOR', name: 'brand' });
+ * ```
+ *
+ * @public
+ */
+export declare function filterVariables(variables: FigmaVariable[], criteria: {
+    resolvedType?: ResolvedType;
+    name?: string;
+}): FigmaVariable[];

package/dist/src/utils/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @packageDocumentation
+ * Barrel file for stateless utility functions in @figma-vars/hooks.
+ *
+ * @summary
+ * Provides centralized exports of utility functions for manipulating and querying Figma variables and design tokens.
+ *
+ * @remarks
+ * Utilities exported here are pure functions, fully typed, and designed for use in UI filtering, scripting, and custom workflows.
+ * Import from this barrel for consistent and type-safe access to these helpers.
+ *
+ * @example
+ * ```ts
+ * import { filterVariables } from '@figma-vars/hooks/utils';
+ *
+ * const filtered = filterVariables(allVariables, { resolvedType: 'COLOR' });
+ * ```
+ *
+ * @public
+ */
+export { filterVariables } from './filterVariables';

package/dist/tests/FigmaVarsProvider.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/api/fetcher.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/api/mutator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/constants/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/hooks/useBulkUpdateVariables.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/hooks/useCreateVariable.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/hooks/useDeleteVariable.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/hooks/useMutation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/hooks/useUpdateVariable.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/hooks/useVariableCollections.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/hooks/useVariableModes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/hooks/useVariables.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/mocks/variables.d.ts

@@ -0,0 +1,2 @@
+import { LocalVariablesResponse } from '../../src/types';
+export declare const mockVariablesResponse: LocalVariablesResponse;

package/dist/tests/test-utils.d.ts

@@ -0,0 +1,10 @@
+import { ReactNode } from 'react';
+export declare const TestWrapper: ({ children }: {
+    children: ReactNode;
+}) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Custom renderHook function that automatically wraps hooks with the TestWrapper.
+ * @param hook The hook to render.
+ */
+export declare const renderHookWithWrapper: (hook: () => any) => import('@testing-library/react').RenderHookResult<any, unknown>;
+export * from '@testing-library/react';

package/dist/tests/test-utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figma-vars/hooks",
-  "version": "1.3.3",
+  "version": "1.4.3",
   "description": "Typed React hooks for managing Figma Variables, modes, tokens, and bindings via API.",
   "author": "Mark Learst",
   "license": "MIT",
@@ -60,6 +60,7 @@
     "@vitejs/plugin-react": "^4.5.2",
     "@vitest/coverage-v8": "^2.0.5",
     "@vitest/ui": "2.1.9",
+    "dotenv": "^16.5.0",
     "jsdom": "^26.1.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
@@ -84,6 +85,7 @@
     "test:ui": "vitest --ui",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest watch",
-    "postversion": "git push && git push --tags"
+    "postversion": "git push && git push --tags",
+    "create:docs": "npx typedoc src/index.ts --out docs-site/api"
   }
 }