@figma-vars/hooks 1.0.10 → 1.1.1

package/README.md

@@ -1,62 +1,85 @@
-# figma-vars-hooks
+# @figma-vars/hooks
 
-A modern, type-safe React hooks & utilities library for the [Figma Variables API](https://www.figma.com/developers/api#variables). Fetch, update, and sync design tokens between Figma and your app, Storybook, or design system dashboard.
+A modern, type-safe, and flexible React hooks library for the [Figma Variables API](https://www.figma.com/developers/api#variables).
+
+Built for the modern web, this library provides a suite of hooks and utilities to fetch, manage, and mutate your design tokens, making it easy to sync them between Figma and your React applications, Storybooks, or design system dashboards.
 
 ---
 
 ## 🚀 Features
 
-- **React 19+ hooks** for fetching and updating Figma variables, collections, and modes
-- **Mutation utilities** for creating, updating, and deleting variables
-- **TypeScript-first**: strict, ergonomic types for all API surfaces
-- **Storybook/Next.js ready** for live token dashboards
-- **Experimental/advanced hooks** for power users
+- **✅ Token Agnostic for the Best DX**: Our library doesn't care _how_ you get your Figma token. Use environment variables, `localStorage`, a state management library, or even a simple input field. This framework-agnostic approach means it works seamlessly with Vite, Next.js, Create React App, and more, without locking you into a specific build tool.
+- **⚛️ Modern React Hooks**: A full suite of hooks for fetching Figma variables, collections, and modes, built on top of `swr` for efficient caching, revalidation, and performance.
+- **✍️ Mutation Utilities**: Simple, promise-based functions for creating, updating, and deleting variables.
+- **🔒 TypeScript-first**: Strictly typed for an ergonomic and safe developer experience. Get autocompletion for all API responses.
+- **📖 Storybook & Next.js Ready**: Perfect for building live design token dashboards or style guides.
 
 ---
 
 ## 📦 Install
 
 ```bash
-npm install figma-vars-hooks
+npm install @figma-vars/hooks
 # or
-yarn add figma-vars-hooks
+yarn add @figma-vars/hooks
 # or
-pnpm add figma-vars-hooks
+pnpm add @figma-vars/hooks
 ```
 
-> **Peer dependency:** React 19+
+> **Peer dependencies:** You'll need `react`, `react-dom`, and `swr`.
 
 ---
 
-## 🛠️ Setup: Figma API Token
+## 🛠️ Setup & Usage
 
-Set your Figma Personal Access Token as an environment variable in your app (Vite example):
+The library is designed to be as flexible as possible. You provide the Figma token and file key, and the hooks handle the rest.
 
-```env
-VITE_FIGMA_TOKEN=your-figma-token-here
-```
+Wrap your application (or the relevant component tree) with the `FigmaVarsProvider`. This makes the Figma token and file key available to all the hooks.
 
----
+```tsx
+// src/main.tsx or App.tsx
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { FigmaVarsProvider } from '@figma-vars/hooks'
+import App from './App'
+
+// The token can come from anywhere: .env, localStorage, state, etc.
+const FIGMA_TOKEN = import.meta.env.VITE_FIGMA_TOKEN
+const FIGMA_FILE_KEY = 'your-figma-file-key'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <FigmaVarsProvider
+      token={FIGMA_TOKEN}
+      fileKey={FIGMA_FILE_KEY}>
+      <App />
+    </FigmaVarsProvider>
+  </React.StrictMode>
+)
+```
 
-## ⚡ Quick Start Example
+Now, you can use the hooks anywhere in your app:
 
 ```tsx
-import { useVariables } from 'figma-vars-hooks'
+// src/components/TokenList.tsx
+import { useVariables } from '@figma-vars/hooks'
 
-export function TokenList({ fileKey }: { fileKey: string }) {
-  const { variables, loading, error, refresh } = useVariables(fileKey)
+export function TokenList() {
+  const { data, isLoading, error } = useVariables()
 
-  if (loading) return <div>Loading…</div>
+  if (isLoading) return <div>Loading tokens...</div>
   if (error) return <div>Error: {error.message}</div>
 
+  // The 'data' object contains variables, collections, and modes
+  const variables = Object.values(data?.variables ?? {})
+
   return (
     <ul>
-      {variables?.map((v) => (
-        <li key={v.id}>
-          {v.name}: {v.value}
+      {variables.map((variable) => (
+        <li key={variable.id}>
+          {variable.name}: {JSON.stringify(variable.valuesByMode)}
         </li>
       ))}
-      <button onClick={refresh}>Refresh</button>
     </ul>
   )
 }
@@ -68,51 +91,43 @@ export function TokenList({ fileKey }: { fileKey: string }) {
 
 ### Core Hooks
 
-- `useFigmaToken()` – Get the current Figma API token
-- `useVariables(fileKey, options?)` – Fetch variables for a Figma file (with polling/refresh)
-- `useVariableCollections(fileKey)` – Fetch variable collections for a file
-- `useVariableModes(collectionId)` – Fetch variable modes for a collection
+- `useVariables()`: Fetches all local variables, collections, and modes for the file key provided to the `FigmaVarsProvider`.
+- `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.
 
 ### Mutations
 
-- `createVariable(fileKey, variableData)` – Create a new variable
-- `updateVariable(fileKey, variableId, newData)` – Update a variable
-- `deleteVariable(fileKey, variableId)` – Delete a variable
-- `updateVariableValues(variableId, values)` – Update variable values across modes
-
-### Utilities
-
-- `filterVariables(variables, { type?, name? })` – Filter variables by type/name
-- `VariablesCache` – Simple in-memory cache for variable lists
-- `fetchHelpers`, `authHelpers` – Internal helpers (advanced)
+- `createVariable(token, fileKey, variableData)`
+- `updateVariable(token, fileKey, variableId, newData)`
+- `deleteVariable(token, fileKey, variableId)`
+- `bulkUpdateVariables(token, fileKey, variables)`
 
 ### Types
 
-All types are exported from `figma-vars-hooks/types` (see `src/types/`).
-
----
-
-## 🧪 Experimental/Advanced Hooks
-
-- `useVariableAliases` – Manage local variable aliases (not in Figma API)
-- `useVariableBindings` – Bind variables to UI components (not in Figma API)
-- `usePublishVars`, `useSync` – Placeholders for future publish/sync features
-
-> These are opt-in and may change—see `src/experimental/` for details.
+All types are exported from `@figma-vars/hooks`. The core response type from Figma is `Variables_LocalVariablesResponse`.
 
 ---
 
 ## 📚 Storybook & Next.js Integration
 
-Use these hooks in your Storybook stories or Next.js pages to build live design token dashboards. Example:
+The provider model makes integration trivial. Simply wrap your Storybook stories or Next.js pages with the `FigmaVarsProvider`.
 
 ```tsx
 // In a Storybook story
-import { useVariables } from 'figma-vars-hooks'
-
-export const TokensStory = () => {
-  const { variables } = useVariables('YOUR_FILE_KEY')
-  return <pre>{JSON.stringify(variables, null, 2)}</pre>
+import { FigmaVarsProvider, useVariables } from '@figma-vars/hooks'
+
+export const TokensStory = () => (
+  <FigmaVarsProvider
+    token="YOUR_TOKEN"
+    fileKey="YOUR_FILE_KEY">
+    <TokenList />
+  </FigmaVarsProvider>
+)
+
+const TokenList = () => {
+  const { data } = useVariables()
+  return <pre>{JSON.stringify(data?.variables, null, 2)}</pre>
 }
 ```
 
@@ -120,14 +135,8 @@ export const TokensStory = () => {
 
 ## 📝 Contributing
 
-PRs and issues welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+PRs and issues are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## 📄 License
 
 MIT
-
----
-
-## 🙏 Credits
-
-Built by Mark Learst and contributors. Inspired by the Figma community and the need for seamless design token workflows.

package/dist/constants/index.d.ts

@@ -1,11 +1,3 @@
 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;
-export declare const FIGMA_COLLECTIONS_ENDPOINT: (fileKey: string) => string;
-export declare const CREATE_VARIABLE_ACTION = "CREATE";
-export declare const UPDATE_VARIABLE_ACTION = "UPDATE";
-export declare const DELETE_VARIABLE_ACTION = "DELETE";
-export declare const DEFAULT_HEADERS: {
-    'Content-Type': string;
-};
-export declare const DEFAULT_ERROR_MESSAGE = "An error occurred while communicating with the Figma API.";

package/dist/contexts/FigmaTokenContext.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+interface FigmaTokenContextType {
+    token: string | null;
+}
+interface FigmaVarsProviderProps {
+    children: ReactNode;
+    token: string | null;
+}
+export declare const FigmaVarsProvider: ({ children, token, }: FigmaVarsProviderProps) => import("react/jsx-runtime").JSX.Element;
+export declare const useFigmaTokenContext: () => FigmaTokenContextType;
+export {};