@figma-vars/hooks 3.0.0-beta.1 → 3.1.0

package/dist/index.mjs

@@ -1,201 +1,357 @@
-import { jsx as _ } from "react/jsx-runtime";
-import { createContext as I, useContext as v, useMemo as d, useReducer as R, useCallback as g } from "react";
-import C from "swr";
-const f = I(void 0), N = ({
-  children: t,
-  token: o,
-  fileKey: e,
-  fallbackFile: r
+import { jsx as O } from "react/jsx-runtime";
+import { createContext as P, useId as _, useMemo as p, useContext as x, useReducer as L, useRef as m, useEffect as g, useCallback as T } from "react";
+import V, { useSWRConfig as j } from "swr";
+import { f as A, E as b, a as E, m as y, F as h, b as D } from "./index-ClHLYVvu.js";
+import { c as ie } from "./index-ClHLYVvu.js";
+const C = P(void 0);
+function S(e) {
+  if (typeof e != "object" || e === null)
+    return !1;
+  const r = e;
+  if (typeof r.meta != "object" || r.meta === null)
+    return !1;
+  const t = r.meta;
+  return !(typeof t.variableCollections != "object" || t.variableCollections === null || typeof t.variables != "object" || t.variables === null);
+}
+function I(e) {
+  if (S(e))
+    return e;
+}
+const W = ({
+  children: e,
+  token: r,
+  fileKey: t,
+  fallbackFile: o,
+  swrConfig: n
 }) => {
-  const s = r === void 0 ? { token: o, fileKey: e } : { token: o, fileKey: e, fallbackFile: r };
-  return /* @__PURE__ */ _(f.Provider, { value: s, children: t });
-}, u = () => {
-  const t = v(f);
-  if (t === void 0)
-    throw new Error("useFigmaTokenContext must be used within a FigmaVarsProvider");
-  return t;
-}, p = "https://api.figma.com", h = `${p}/v1/variables`, w = h, A = (t) => `${h}/${t}`, b = "application/json", T = "X-FIGMA-TOKEN", c = "A Figma API token is required.", P = "An error occurred while fetching data from the Figma API.";
-async function M(t, o) {
-  if (!o)
-    throw new Error(c);
-  const e = await fetch(t, {
-    method: "GET",
-    headers: {
-      [T]: o,
-      "Content-Type": b
-    }
-  });
-  if (!e.ok) {
-    let r = P;
-    try {
-      const s = await e.json();
-      s != null && s.message && (r = s.message);
-    } catch {
+  const a = _(), c = p(() => `figma-vars-provider-${a}`, [a]), u = p(() => {
+    if (o) {
+      if (typeof o == "object") {
+        const s = I(o);
+        if (s)
+          return s;
+        process.env.NODE_ENV !== "production" && console.warn(
+          "[figma-vars-hooks] fallbackFile object does not match expected Figma Variables API response structure. Expected { meta: { variableCollections: {...}, variables: {...} } }"
+        );
+        return;
+      }
+      if (typeof o == "string")
+        try {
+          const s = JSON.parse(o), l = I(s);
+          if (l)
+            return l;
+          process.env.NODE_ENV !== "production" && console.warn(
+            "[figma-vars-hooks] Parsed fallbackFile JSON does not match expected Figma Variables API response structure. Expected { meta: { variableCollections: {...}, variables: {...} } }"
+          );
+          return;
+        } catch (s) {
+          process.env.NODE_ENV !== "production" && console.error(
+            `[figma-vars-hooks] Failed to parse fallbackFile JSON: ${s instanceof Error ? s.message : "Unknown error"}`
+          );
+          return;
+        }
     }
-    throw new Error(r);
-  }
-  return e.json();
+  }, [o]), i = p(() => {
+    const s = {
+      token: r,
+      fileKey: t,
+      providerId: c,
+      ...n !== void 0 && { swrConfig: n }
+    };
+    return o === void 0 ? s : {
+      ...s,
+      fallbackFile: o,
+      // Keep for backward compatibility
+      parsedFallbackFile: u
+      // Pre-parsed version for hooks to use
+    };
+  }, [r, t, o, u, c, n]);
+  return /* @__PURE__ */ O(C.Provider, { value: i, children: e });
+}, d = () => {
+  const e = x(C);
+  if (e === void 0)
+    throw new Error(
+      "useFigmaTokenContext must be used within a FigmaVarsProvider"
+    );
+  return e;
+};
+function N(e) {
+  const { fileKey: r, token: t, providerId: o, hasFallback: n } = e;
+  return !!(t && r) && t && r ? [`https://api.figma.com/v1/files/${r}/variables/local`, t] : n ? [`fallback-${o ?? "default"}`, "fallback"] : null;
+}
+function B(e) {
+  const { fileKey: r, token: t, providerId: o, hasFallback: n } = e;
+  return !!(t && r) && t && r ? [`https://api.figma.com/v1/files/${r}/variables/published`, t] : n ? [`fallback-${o ?? "default"}`, "fallback"] : null;
 }
-const y = () => {
-  const { token: t, fileKey: o } = u(), e = t && o ? `https://api.figma.com/v1/files/${o}/variables/local` : null;
-  return C(
-    e && t ? [e, t] : null,
-    e && t ? ([s, n]) => M(s, n) : () => Promise.resolve(void 0)
+function F(e) {
+  const { fileKey: r, token: t, providerId: o, hasFallback: n } = e, a = [];
+  return t && r && (a.push([
+    `https://api.figma.com/v1/files/${r}/variables/local`,
+    t
+  ]), a.push([
+    `https://api.figma.com/v1/files/${r}/variables/published`,
+    t
+  ])), n && o && a.push([`fallback-${o}`, "fallback"]), a;
+}
+const K = () => {
+  const {
+    token: e,
+    fileKey: r,
+    fallbackFile: t,
+    parsedFallbackFile: o,
+    providerId: n,
+    swrConfig: a
+  } = d(), u = N({
+    fileKey: r,
+    token: e,
+    providerId: n,
+    hasFallback: !!(t || o)
+  });
+  return V(
+    u,
+    async (...s) => {
+      if (o)
+        return o;
+      if (t && typeof t == "object")
+        return t;
+      const [l, f] = Array.isArray(s[0]) ? s[0] : [s[0], s[1]];
+      if (!l || !f)
+        throw new Error("Missing URL or token for live API request");
+      return A(l, f);
+    },
+    a
   );
-}, S = () => {
-  const { data: t } = y(), o = d(
-    () => t != null && t.meta ? Object.values(t.meta.variableCollections) : [],
-    [t]
-  ), e = d(
-    () => t != null && t.meta ? t.meta.variableCollections : {},
-    [t]
+}, H = () => {
+  const { data: e } = K(), r = p(
+    () => e != null && e.meta ? Object.values(e.meta.variableCollections) : [],
+    [e]
+  ), t = p(
+    () => e != null && e.meta ? e.meta.variableCollections : {},
+    [e]
   );
   return {
-    collections: o,
-    collectionsById: e
+    collections: r,
+    collectionsById: t
   };
-}, B = () => {
-  const { data: t } = y();
-  return d(() => {
-    const o = [], e = {}, r = {};
-    if (t != null && t.meta)
-      for (const s of Object.values(t.meta.variableCollections)) {
-        o.push(...s.modes), e[s.id] = s.modes;
-        for (const n of s.modes)
-          r[n.modeId] = n;
+}, Y = () => {
+  const { data: e } = K();
+  return p(() => {
+    const r = [], t = {}, o = {};
+    if (e != null && e.meta)
+      for (const n of Object.values(
+        e.meta.variableCollections
+      )) {
+        r.push(...n.modes), t[n.id] = n.modes;
+        for (const a of n.modes)
+          o[a.modeId] = a;
       }
     return {
-      modes: o,
-      modesByCollectionId: e,
-      modesById: r
+      modes: r,
+      modesByCollectionId: t,
+      modesById: o
     };
-  }, [t]);
+  }, [e]);
 };
-function O(t, o) {
-  switch (o.type) {
+function M(e, r) {
+  switch (r.type) {
     case "loading":
-      return { ...t, status: "loading", error: null };
+      return { ...e, status: "loading", error: null };
     case "success":
-      return { ...t, status: "success", data: o.payload };
+      return { ...e, status: "success", data: r.payload };
     case "error":
-      return { ...t, status: "error", error: o.payload };
+      return { ...e, status: "error", error: r.payload };
     default:
-      return t;
+      return e;
   }
 }
-const l = (t) => {
-  const o = {
+const k = (e, r) => {
+  const { throwOnError: t = !1 } = {}, o = {
     status: "idle",
     data: null,
     error: null
-  }, [e, r] = R(O, o);
-  return {
-    mutate: g(
-      async (n) => {
-        r({ type: "loading" });
+  }, [n, a] = L(M, o), c = m(e), u = m({ throwOnError: t }), i = m(!0), s = m(0);
+  return g(() => {
+    c.current = e, u.current = { throwOnError: t };
+  }, [e, t]), g(() => (i.current = !0, () => {
+    i.current = !1;
+  }), []), {
+    mutate: T(
+      async (f) => {
+        if (!i.current)
+          return;
+        const w = ++s.current;
+        a({ type: "loading" });
         try {
-          const a = await t(n);
-          return r({ type: "success", payload: a }), a;
-        } catch (a) {
-          r({ type: "error", payload: a });
+          const v = await c.current(f);
+          return i.current && w === s.current && a({ type: "success", payload: v }), v;
+        } catch (v) {
+          const R = v;
+          if (i.current && w === s.current && a({ type: "error", payload: R }), u.current.throwOnError)
+            throw R;
           return;
         }
       },
-      [t]
+      []
+      // Empty deps array - mutationFn and options are accessed via refs
     ),
-    ...e,
-    isLoading: e.status === "loading",
-    isSuccess: e.status === "success",
-    isError: e.status === "error"
+    ...n,
+    isLoading: n.status === "loading",
+    isSuccess: n.status === "success",
+    isError: n.status === "error"
   };
-};
-async function m(t, o, e, r) {
-  if (!o)
-    throw new Error(c);
-  const a = {
-    method: {
-      CREATE: "POST",
-      UPDATE: "PUT",
-      DELETE: "DELETE"
-    }[e],
-    headers: {
-      "Content-Type": "application/json",
-      [T]: o
-    }
-  };
-  r && (a.body = JSON.stringify(r));
-  const i = await fetch(`${p}${t}`, a);
-  if (!i.ok) {
-    const E = await i.json().catch(() => ({}));
-    throw new Error(E.err || E.message || "An API error occurred");
-  }
-  return i.status === 204 || !i.body ? {} : i.json();
-}
-const G = () => {
-  const { token: t } = u();
-  return l(async (e) => {
-    if (!t)
-      throw new Error(c);
-    return await m(
-      w,
-      t,
-      "CREATE",
-      e
-    );
+}, z = () => {
+  const { token: e, fileKey: r } = d();
+  return k(async (o) => {
+    if (!e)
+      throw new Error(b);
+    if (!r)
+      throw new Error(E);
+    return await y(h(r), e, "CREATE", {
+      variables: [
+        {
+          action: "CREATE",
+          ...o
+        }
+      ]
+    });
   });
-}, j = () => {
-  const { token: t } = u();
-  return l(
-    async ({ variableId: e, payload: r }) => {
-      if (!t)
-        throw new Error(c);
-      return await m(
-        A(e),
-        t,
+}, X = () => {
+  const { token: e, fileKey: r } = d();
+  return k(
+    async ({
+      variableId: o,
+      payload: n
+    }) => {
+      if (!e)
+        throw new Error(b);
+      if (!r)
+        throw new Error(E);
+      return await y(
+        h(r),
+        e,
         "UPDATE",
-        r
+        {
+          variables: [
+            {
+              action: "UPDATE",
+              id: o,
+              ...n
+            }
+          ]
+        }
       );
     }
   );
-}, k = () => {
-  const { token: t } = u();
-  return l(async (e) => {
-    if (!t)
-      throw new Error(c);
-    return await m(
-      A(e),
-      t,
-      "DELETE",
-      void 0
-    );
+}, Z = () => {
+  const { token: e, fileKey: r } = d();
+  return k(async (o) => {
+    if (!e)
+      throw new Error(b);
+    if (!r)
+      throw new Error(E);
+    return await y(h(r), e, "DELETE", {
+      variables: [
+        {
+          action: "DELETE",
+          id: o
+        }
+      ]
+    });
   });
-}, L = () => {
-  const { token: t } = u();
-  return l(async (e) => {
-    if (!t)
-      throw new Error(c);
-    return await m(
-      w,
-      t,
-      "CREATE",
-      e
+}, ee = () => {
+  const { token: e, fileKey: r } = d();
+  return k(async (o) => {
+    if (!e)
+      throw new Error(b);
+    if (!r)
+      throw new Error(E);
+    return await y(
+      h(r),
+      e,
+      "UPDATE",
+      o
     );
   });
-};
-function x(t, o) {
-  return t.filter((e) => {
-    let r = !0;
-    return o.resolvedType && (r = r && e.resolvedType === o.resolvedType), o.name && (r = r && e.name.includes(o.name)), r;
+}, re = () => {
+  const { mutate: e } = j(), { token: r, fileKey: t, fallbackFile: o, providerId: n } = d(), a = !!o;
+  return {
+    invalidate: () => {
+      const i = F({
+        fileKey: t,
+        token: r,
+        providerId: n,
+        hasFallback: a
+      });
+      for (const s of i)
+        e(s);
+    },
+    revalidate: () => {
+      const i = F({
+        fileKey: t,
+        token: r,
+        providerId: n,
+        hasFallback: a
+      });
+      for (const s of i)
+        e(s, void 0, { revalidate: !0 });
+    }
+  };
+}, te = () => {
+  const {
+    token: e,
+    fileKey: r,
+    fallbackFile: t,
+    parsedFallbackFile: o,
+    providerId: n,
+    swrConfig: a
+  } = d(), u = B({
+    fileKey: r,
+    token: e,
+    providerId: n,
+    hasFallback: !!(t || o)
   });
+  return V(
+    u,
+    async (...s) => {
+      if (o)
+        return o;
+      if (t && typeof t == "object")
+        return t;
+      const [l, f] = Array.isArray(s[0]) ? s[0] : [s[0], s[1]];
+      if (!l || !f)
+        throw new Error("Missing URL or token for live API request");
+      return A(l, f);
+    },
+    a
+  );
+};
+function U(e) {
+  return e instanceof D;
+}
+function $(e) {
+  return U(e) ? e.statusCode : null;
+}
+function oe(e, r = "An error occurred") {
+  return e instanceof Error ? e.message || r : typeof e == "string" ? e : r;
+}
+function ne(e, r) {
+  return $(e) === r;
 }
 export {
-  N as FigmaVarsProvider,
-  x as filterVariables,
-  L as useBulkUpdateVariables,
-  G as useCreateVariable,
-  k as useDeleteVariable,
-  j as useUpdateVariable,
-  S as useVariableCollections,
-  B as useVariableModes,
-  y as useVariables
+  D as FigmaApiError,
+  W as FigmaVarsProvider,
+  ie as filterVariables,
+  oe as getErrorMessage,
+  $ as getErrorStatus,
+  ne as hasErrorStatus,
+  U as isFigmaApiError,
+  ee as useBulkUpdateVariables,
+  z as useCreateVariable,
+  Z as useDeleteVariable,
+  re as useInvalidateVariables,
+  te as usePublishedVariables,
+  X as useUpdateVariable,
+  H as useVariableCollections,
+  Y as useVariableModes,
+  K as useVariables
 };

package/dist/types/contexts.d.ts

@@ -1,5 +1,6 @@
 import { ReactNode } from 'react';
-import { LocalVariablesResponse } from 'types';
+import { SWRConfiguration } from 'swr';
+import { LocalVariablesResponse, PublishedVariablesResponse } from 'types';
 /**
  * Central context shape for FigmaVars—provides authentication and file context to all hooks and consumers in the tree.
  *
@@ -40,8 +41,14 @@ export interface FigmaTokenContextType {
     /**
      * Optional fallback variable JSON file for offline or static use cases.
      * Allows FigmaVars to function without a live API request.
+     * @deprecated Use parsedFallbackFile instead. This is kept for backward compatibility.
      */
-    fallbackFile?: LocalVariablesResponse | string;
+    fallbackFile?: LocalVariablesResponse | PublishedVariablesResponse | string;
+    /**
+     * Optional SWR configuration to customize caching, revalidation, and error handling behavior.
+     * Applied to all SWR hooks within this provider.
+     */
+    swrConfig?: SWRConfiguration | undefined;
 }
 /**
  * Props for the FigmaVarsProvider component, which injects Figma API authentication and file scoping for all descendant hooks and utilities.
@@ -83,6 +90,26 @@ export interface FigmaVarsProviderProps {
     /**
      * Optional fallback variable JSON file used when the API is unavailable or skipped.
      */
-    fallbackFile?: LocalVariablesResponse | string;
+    fallbackFile?: LocalVariablesResponse | PublishedVariablesResponse | string;
+    /**
+     * Optional SWR configuration to customize caching, revalidation, and error handling.
+     * Common options: `revalidateOnFocus`, `dedupingInterval`, `errorRetryCount`, `onError`, etc.
+     *
+     * @example
+     * ```tsx
+     * <FigmaVarsProvider
+     *   token={token}
+     *   fileKey={fileKey}
+     *   swrConfig={{
+     *     revalidateOnFocus: false,
+     *     dedupingInterval: 5000,
+     *     errorRetryCount: 3,
+     *   }}
+     * >
+     *   <App />
+     * </FigmaVarsProvider>
+     * ```
+     */
+    swrConfig?: SWRConfiguration;
 }
 //# sourceMappingURL=contexts.d.ts.map

package/dist/types/contexts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contexts.d.ts","sourceRoot":"","sources":["../../src/types/contexts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,OAAO,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;OAGG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;OAGG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;OAEG;IACH,YAAY,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAAC;CAChD"}
+{"version":3,"file":"contexts.d.ts","sourceRoot":"","sources":["../../src/types/contexts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,KAAK,CAAA;AAC3C,OAAO,KAAK,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,OAAO,CAAA;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;OAGG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,sBAAsB,GAAG,0BAA0B,GAAG,MAAM,CAAA;IAe3E;;;OAGG;IACH,SAAS,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAA;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAA;IACnB;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;OAGG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB;;OAEG;IACH,YAAY,CAAC,EAAE,sBAAsB,GAAG,0BAA0B,GAAG,MAAM,CAAA;IAC3E;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAA;CAC7B"}