@figma-vars/hooks 1.3.2 → 1.4.3

package/README.md

@@ -1,4 +1,6 @@
-# @figma-vars/hooks
+<p align="left">
+  <img src="assets/figma-vars-tagline-light.png" alt="FigmaVars Logo" width="700px" />
+</p>
 
 A fast, typed React 19 hooks library for the Figma Variables API: fetch, update, and manage design tokens via the official [Figma REST API](https://www.figma.com/developers/api#variables).
 
@@ -6,6 +8,7 @@ Built for the modern web, this library provides a suite of hooks to fetch, manag
 
 ![Status](https://img.shields.io/badge/status-stable-brightgreen)
 ![CI](https://github.com/marklearst/figma-vars-hooks/actions/workflows/publish.yml/badge.svg)
+[![codecov](https://codecov.io/gh/marklearst/figma-vars-hooks/branch/main/graph/badge.svg)](https://codecov.io/gh/marklearst/figma-vars-hooks)
 ![License](https://img.shields.io/github/license/marklearst/figma-vars-hooks)
 ![GitHub last commit](https://img.shields.io/github/last-commit/marklearst/figma-vars-hooks)
 ![GitHub code size](https://img.shields.io/github/languages/code-size/marklearst/figma-vars-hooks)
@@ -105,21 +108,26 @@ Here's an example of creating a new variable:
 ```tsx
 // src/components/CreateVariableForm.tsx
 import { useCreateVariable } from '@figma-vars/hooks'
+import type { CreateVariablePayload } from '@figma-vars/hooks'
 
-function CreateVariableForm({ collectionId, modeId }) {
+function CreateVariableForm({ collectionId }: { collectionId: string }) {
   const { mutate, data, isLoading, error } = useCreateVariable()
 
-  const handleSubmit = (event) => {
+  const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {
     event.preventDefault()
-    const variableName = event.target.elements.variableName.value
-
-    mutate({
-      name: `colors/${variableName}`,
-      collectionId: collectionId,
-      valuesByMode: {
-        [modeId]: { r: 1, g: 0, b: 0, a: 1 },
-      },
-    })
+    const form = event.currentTarget
+    const variableName = (
+      form.elements.namedItem('variableName') as HTMLInputElement
+    )?.value
+
+    if (!variableName) return
+
+    const payload: CreateVariablePayload = {
+      name: variableName,
+      variableCollectionId: collectionId,
+      resolvedType: 'COLOR', // Example type
+    }
+    mutate(payload)
   }
 
   return (
@@ -140,13 +148,76 @@ function CreateVariableForm({ collectionId, modeId }) {
 }
 ```
 
+### Figma PAT Security
+
+When using the Figma API, it's essential to keep your Personal Access Token (PAT) secure. Here are some best practices:
+
+- Never hardcode your PAT in your code.
+- Use environment variables or a secure storage mechanism to store your PAT.
+- Limit the scope of your PAT to only the necessary permissions.
+- Rotate your PAT regularly.
+
+### Advanced Usage
+
+For advanced use cases, you can use the `useFigmaToken` hook to access the token and file key from the context.
+
+```tsx
+// src/components/AdvancedUsage.tsx
+import { useFigmaToken } from '@figma-vars/hooks'
+
+function AdvancedUsage() {
+  const { token, fileKey } = useFigmaToken()
+
+  // Use the token and file key to make custom API requests
+  const apiRequest = async () => {
+    const response = await fetch(
+      `https://api.figma.com/v1/files/${fileKey}/variables`,
+      {
+        headers: {
+          'X-Figma-Token': token,
+        },
+      }
+    )
+
+    const data = await response.json()
+    console.log(data)
+  }
+
+  return <button onClick={apiRequest}>Make API Request</button>
+}
+```
+
+### Error Handling
+
+All hooks return an `error` state that you can use to handle errors.
+
+```tsx
+// src/components/ErrorHandling.tsx
+import { useVariables } from '@figma-vars/hooks'
+
+function ErrorHandling() {
+  const { data, isLoading, error } = useVariables()
+
+  if (error) {
+    return (
+      <div>
+        <h2>Error</h2>
+        <p>{error.message}</p>
+      </div>
+    )
+  }
+
+  // Render data or loading state
+}
+```
+
 ---
 
 ## 🧩 API Reference
 
 ### Core Hooks
 
-- `useVariables()`: Fetches all local variables for the file key provided to the `FigmaVarsProvider`. Returns an object with `data`, `isLoading`, and `error` properties. The `data` object contains `variables`, `variableCollections`, and `modes` from the Figma API.
+- `useVariables()`: Fetches all local variables for the file key provided to the `FigmaVarsProvider`. Returns a SWR hook state with `data`, `isLoading`, and `error` properties. The actual Figma response is in `data.data`.
 - `useVariableCollections()`: A convenience hook that returns just the variable collections from the main `useVariables` data.
 - `useVariableModes()`: A convenience hook that returns just the variable modes from the main `useVariables` data.
 - `useFigmaToken()`: A simple hook to access the token and file key from the context.
@@ -155,14 +226,14 @@ function CreateVariableForm({ collectionId, modeId }) {
 
 All mutation hooks return an object with the following shape: `{ mutate, data, isLoading, error }`.
 
-- `useCreateVariable()`: Creates a new variable. The `mutate` function expects the variable data as its payload.
-- `useUpdateVariable()`: Updates an existing variable. The `mutate` function expects an object with `id` and the `data` to update.
-- `useDeleteVariable()`: Deletes a variable. The `mutate` function expects the `id` of the variable to delete.
-- `useBulkUpdateVariables()`: Updates multiple variables in a single batch operation. The `mutate` function expects an array of variables to update.
+- `useCreateVariable()`: Creates a new variable. The `mutate` function expects a `CreateVariablePayload` object.
+- `useUpdateVariable()`: Updates an existing variable. The `mutate` function expects an object `{ variableId, payload }` where `payload` is an `UpdateVariablePayload`.
+- `useDeleteVariable()`: Deletes a variable. The `mutate` function expects the `variableId` (string) of the variable to delete.
+- `useBulkUpdateVariables()`: Creates, updates, or deletes multiple entities in a single batch operation. The `mutate` function expects a `BulkUpdatePayload` object.
 
 ### Types
 
-All types are exported from `@figma-vars/hooks`. The core response type from Figma for local variables is `Variables_LocalVariablesResponse`.
+All types are exported from `@figma-vars/hooks`. The core response type from Figma for local variables is `LocalVariablesResponse`.
 
 ---
 
@@ -196,5 +267,5 @@ PRs and issues are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for gu
 
 ## 📝 License
 
-This project is licensed under the [MIT License](LICENSE).  
+This project is licensed under the [MIT License](LICENSE).
 © 2024–2025 Mark Learst