@fileverse/heartbit-react
Advanced tools
Comparing version 0.0.23 to 0.0.24
@@ -38,4 +38,4 @@ /// <reference types="react" /> | ||
export declare interface HeartBitUIProps { | ||
onMouseUp?: (event: React.MouseEvent<HTMLCanvasElement, MouseEvent>) => void; | ||
onMouseDown?: (event: React.MouseEvent<HTMLCanvasElement, MouseEvent>) => void; | ||
onMouseUp?: (event: React.MouseEvent<HTMLCanvasElement, MouseEvent> | React.TouchEvent<HTMLCanvasElement>) => void; | ||
onMouseDown?: (event: React.MouseEvent<HTMLCanvasElement, MouseEvent> | React.TouchEvent<HTMLCanvasElement>) => void; | ||
scale?: number; | ||
@@ -42,0 +42,0 @@ defaultFillPos?: DefaultFillRange; |
{ | ||
"name": "@fileverse/heartbit-react", | ||
"version": "0.0.23", | ||
"version": "0.0.24", | ||
"type": "module", | ||
@@ -45,3 +45,3 @@ "main": "./dist/index.umd.js", | ||
"classnames": "^2.5.1", | ||
"@fileverse/heartbit-core": "0.0.2" | ||
"@fileverse/heartbit-core": "0.0.21" | ||
}, | ||
@@ -48,0 +48,0 @@ "scripts": { |
219
README.md
@@ -1,24 +0,17 @@ | ||
# @fileverse/heartbit-react | ||
# HeartBit React | ||
### About the project | ||
## Introduction | ||
This library contains react components to capture on chain timespent by a user. At the end of the flow an ERC1155 NFT is minted to the user address. | ||
A plug-and-play integration of the HeartBit SDK, which is a wrapper around [HeartBitCore](https://github.com/fileverse/HeartBitSDK/tree/main/packages/heartbit-core). | ||
Main Exports of this library are | ||
## Getting Started | ||
- HeartBitUI - A heart component made with canvas | ||
- HeartBitProvider and useHeartbit - Provider and hook that exposes heartbit mint functionality to its children | ||
- HeartBit - A Plug and Play integration of the HeartBitUI and HeartBitProvider | ||
### Installation | ||
### Supported Chain | ||
You can install using `npm` or `yarn`: | ||
- Sepolia - 0xaa36a7 | ||
- base - 0x2105 | ||
### Installation | ||
``` | ||
```javascript | ||
npm install --save @fileverse/heartbit-react | ||
//or | ||
// or | ||
@@ -28,100 +21,68 @@ yarn add @fileverse/heartbit-react | ||
### Dependencies | ||
### Import Packages | ||
**Required Peer Dependencies** | ||
These libraries are not bundled with in this package and required at runtime: | ||
Import the core component of the package `HeartBit`: | ||
- react | ||
- react-dom | ||
**Other Dependencies** | ||
- @fileverse/heartbit-core | ||
- classnames | ||
## HeartBitUI | ||
### Interface | ||
```javascript | ||
type TotalFillRange = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10; | ||
import { HeartBit } from "@fileverse/heartbit-react"; | ||
``` | ||
type DefaultFillRange = 1 | 2 | 3 | 4 | 5; | ||
### Integrate HeartBit Functionality | ||
interface HeartBitUIProps { | ||
onMouseUp?: (event: React.MouseEvent<HTMLCanvasElement, MouseEvent>) => void; | ||
onMouseDown?: ( | ||
event: React.MouseEvent<HTMLCanvasElement, MouseEvent> | ||
) => void; | ||
scale?: number; // Default Value = 3. size of the canvas, min dimensions width = 13, height = 12. eg: scale = 3 => width: 39px height: 36px | ||
defaultFillPos?: DefaultFillRange; //Default Value = 2. default position of fill in heart on load, onMouseDown the fill will always start from 0 not from defaultFillPos. | ||
startFillPos?: TotalFillRange; // Default Value = 0. start fill position in heart on load, onMouseDown the fill will resume from this position. | ||
isDisabled?: boolean; // Default Value = false. disables all actions. | ||
disableBeatingAnimation?: boolean; // Default Value = false. disables heat beating animation | ||
fillInterval?: number; // Default Value = 750. Interval at which the heart fills in milliseconds | ||
} | ||
``` | ||
First of all, you want to set up your wallet providers. For this example, we will be using the `BrowserProvider` from `ethers` as our provider. We will create a React component that will render `HeartBit`, and we are going to configure the network by passing the `coreOption` as props to it. It requires the `getSignatureArgsHook` as props as well, which it calls internally to get the `message`, `signature`, and optionally an `onMintCallback`, a function that will be called after mint is completed. We would also define `hash` which is a keccak256 hash that will be used for generating the tokenId on the smart contract, and we will use `SIWE` for generating the `message` and `signature`. The code below should do the trick: | ||
### Usage | ||
```javascript | ||
import { HeartBitUI } from "@fileverse/heartbit-react"; | ||
const MyApp = () => { | ||
const provider = new BrowserProvider((window as any).ethereum); | ||
const coreOptions = { | ||
chain: "0xaa36a7" as SupportedChain | ||
} | ||
export const MyApp = () => { | ||
return <HeartBitUI />; | ||
}; | ||
const getSignatureArgsHook = async () => { | ||
const signer = await provider.getSigner() | ||
const address = await signer.getAddress(); | ||
/* | ||
Additionally you can pass a ref to HeartBitUI. | ||
This will expose a onReset function from the component, | ||
on use will reset the heart fill to the defaultFillPos or the startFillPos | ||
*/ | ||
``` | ||
const siweMessage = new SiweMessage({ | ||
domain: window.location.host, | ||
address, | ||
statement: "Hello World!", | ||
uri: window.location.origin, | ||
version: "1", | ||
}); | ||
## HeartBitProvider and useHeartBit | ||
const message = siweMessage.prepareMessage(); | ||
const signature = await signer.signMessage(message); | ||
### Interface | ||
return { | ||
message, | ||
signature, | ||
onMintCallback: () => { | ||
console.log("Minted!") | ||
} | ||
}; | ||
}; | ||
```javascript | ||
type SupportedChain = "0xaa36a7" | "0x2105"; | ||
const hash = keccak256(toUtf8Bytes("MY_APP_TOKEN")); | ||
interface HeartBitCoreOptions { | ||
chain: SupportedChain; | ||
rpcUrl?: string; | ||
return <HeartBit | ||
coreOptions={coreOptions} | ||
getSignatureArgsHook={getSignatureArgsHook} | ||
hash={hash} | ||
/>; | ||
} | ||
``` | ||
interface HeartBitProviderProps { | ||
children: React.ReactNode; | ||
coreOptions: HeartBitCoreOptions; | ||
} | ||
If all the process was successful, you should see a heart on your screen, and when you click and hold it for long, it should fill up. Once released, some NFTs related to the amount of time spent on clicking the button will be minted to the user. | ||
interface TotalHeartBitCountArgs { | ||
hash: string; // keccak256 hash of a string | ||
} | ||
[Here](<(https://codesandbox.io/p/devbox/hearbit-example-cxr375)>) is a working example using HeartBit. | ||
interface HeartBitCountByUserArgs { | ||
hash: string; // keccak256 hash of a string | ||
address: string; // ethereum wallet address | ||
} | ||
## Customization | ||
interface MintHeartBitArgs { | ||
message: string; | ||
signature: string; | ||
startTime: number; // in seconds | ||
endTime: number; // in seconds | ||
hash: string; // keccak256 hash of a string | ||
} | ||
You can attach the HeartBit functionality to any UI component and instead of being restricted by our default heart icon. To achieve this, the `heartbit-react` package exports `HeartBitProvider` and `useHeartBit`. The `HeartBitProvider` is used to configure the core package with the `coreOptions`, and `useHeartBit` exposes the core functions of the HeartBit SDK, which we can call in a React component. Note that it can only be used in the context of `HeartBitProvider`. | ||
interface IHeartBitContext { | ||
getTotalHeartMintsByUser: (opts: HeartBitCountByUserArgs) => Promise<number>; | ||
getTotalHeartBitByHash: (opts: TotalHeartBitCountArgs) => Promise<number>; | ||
mintHeartBit: (opts: MintHeartBitArgs) => Promise<void>; | ||
} | ||
``` | ||
### Example Usage | ||
### Usage | ||
```javascript | ||
import { useState, useEffect } from 'react' | ||
import { HeartBitProvider, useHeartBit } from "@fileverse/heartbit-react" | ||
import { HeartBitProvider } from "@fileverse/heartbit-react" | ||
@@ -134,7 +95,6 @@ const MyApp = () => { | ||
<HeartBitProvider coreOptions={coreOptions}> | ||
<ComponentWithProvider /> | ||
<CustomHeartBit /> | ||
</HeartBitProvider> | ||
) | ||
const ComponentWithProvider = () => { | ||
const CustomHearBit = () => { | ||
const { mintHeartBit, getTotalHeartMintsByUser, getTotalHeartBitByHash } = useHeartBit() | ||
@@ -174,71 +134,2 @@ const [startTime, setStartTime] = useState<number | null>(null) // should be in seconds | ||
## HeartBit | ||
### Interface | ||
```javascript | ||
interface SignatureArgs { | ||
message: string; | ||
signature: string; | ||
onMintCallback?: () => void; // will be called after NFT minting is done | ||
} | ||
interface HeartBitProps | ||
extends Omit<HeartBitUIProps, "isDisabled" | "startFillPos"> { | ||
coreOptions: HeartBitCoreOptions; | ||
getSignatureArgsHook: () => Promise<SignatureArgs>; // this is a required hook, this allows to call sign message operation on the user wallet, must return SignatureArgs | ||
hash: string; // keccak256 hash of a string | ||
address?: string; // user wallet address | ||
showTotalMintsByHash?: boolean; // Default to false, if true will show total mints for a hash to the right of component | ||
showTotalMintsByUser?: boolean; // Defaults to false, if true will show total mints by a user on a hash to right of the component | ||
} | ||
``` | ||
### Usage | ||
```javascript | ||
import { HeartBit, type SupportedChain } from "@fileverse/heartbit-react"; | ||
import { SiweMessage } from "siwe"; | ||
import { BrowserProvider, keccak256, toUtf8Bytes } from "ethers"; | ||
const MyApp = () => { | ||
const provider = new BrowserProvider((window as any).ethereum); | ||
const hash = keccak256(toUtf8Bytes(window.location.href)); | ||
const signMessageHook = async () => { | ||
const signer = await provider.getSigner() | ||
const address = await signer.getAddress(); | ||
const siweMessage = new SiweMessage({ | ||
domain: window.location.host, | ||
address, | ||
statement: "Hello World!", | ||
uri: window.location.origin, | ||
version: "1", | ||
}); | ||
const message = siweMessage.prepareMessage(); | ||
const signature = await signer.signMessage(message); | ||
return { | ||
message, | ||
signature, | ||
onMintCallback: () => { | ||
console.log("Minted!") | ||
} | ||
}; | ||
}; | ||
const coreOptions = { | ||
chain: "0xaa36a7" as SupportedChain | ||
} | ||
return <HeartBit | ||
coreOptions={coreOptions} | ||
getSignatureArgsHook={signMessageHook} | ||
hash={hash} | ||
scale={10} | ||
/>; | ||
} | ||
``` | ||
[Here](https://codesandbox.io/p/devbox/custom-heartbit-example-p6f7gr) is a working example using the `HeartBitProvider` and `useHeartBit`. |
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is not supported yet
14987
3116595
133
+ Added@fileverse/heartbit-core@0.0.21(transitive)
- Removed@fileverse/heartbit-core@0.0.2(transitive)