react-achievements 3.0.0 → 3.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +125 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,6 +2,96 @@
|
|
|
2
2
|
|
|
3
3
|
A flexible and extensible achievement system for React applications. This package provides the foundation for implementing achievements in React applications with support for multiple state management solutions including Redux, Zustand, and Context API. Check the `stories/examples` directory for implementation examples with different state management solutions.
|
|
4
4
|
|
|
5
|
+
<p align="center">
|
|
6
|
+
<img src="https://media4.giphy.com/media/v1.Y2lkPTc5MGI3NjExbnMxdHVqanZvbGR6czJqOTdpejZqc3F3NXh6a2FiM3lmdnB0d3VoOSZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/LYXAZelQMeeYpzbgtT/giphy.gif" alt="React Achievements Demo" width="600" />
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
## Quick Start
|
|
10
|
+
|
|
11
|
+
Here's a complete working example that shows automatic notifications and achievement tracking:
|
|
12
|
+
|
|
13
|
+
```tsx
|
|
14
|
+
import React, { useState } from 'react';
|
|
15
|
+
import {
|
|
16
|
+
AchievementProvider,
|
|
17
|
+
useAchievements,
|
|
18
|
+
BadgesButton,
|
|
19
|
+
BadgesModal
|
|
20
|
+
} from 'react-achievements';
|
|
21
|
+
|
|
22
|
+
// Define a simple achievement
|
|
23
|
+
const achievementConfig = {
|
|
24
|
+
score: [{
|
|
25
|
+
isConditionMet: (value: number) => value >= 100,
|
|
26
|
+
achievementDetails: {
|
|
27
|
+
achievementId: 'score_100',
|
|
28
|
+
achievementTitle: 'Century!',
|
|
29
|
+
achievementDescription: 'Score 100 points',
|
|
30
|
+
achievementIconKey: 'trophy'
|
|
31
|
+
}
|
|
32
|
+
}]
|
|
33
|
+
};
|
|
34
|
+
|
|
35
|
+
// Demo component with all essential features
|
|
36
|
+
const DemoComponent = () => {
|
|
37
|
+
const [isModalOpen, setIsModalOpen] = useState(false);
|
|
38
|
+
const { update, achievements, reset } = useAchievements();
|
|
39
|
+
|
|
40
|
+
return (
|
|
41
|
+
<div>
|
|
42
|
+
<h1>Achievement Demo</h1>
|
|
43
|
+
|
|
44
|
+
{/* Button to trigger achievement */}
|
|
45
|
+
<button onClick={() => update({ score: 100 })}>
|
|
46
|
+
Score 100 points
|
|
47
|
+
</button>
|
|
48
|
+
|
|
49
|
+
{/* Reset button */}
|
|
50
|
+
<button onClick={reset}>
|
|
51
|
+
Reset Achievements
|
|
52
|
+
</button>
|
|
53
|
+
|
|
54
|
+
{/* Shows unlocked achievements count */}
|
|
55
|
+
<p>Unlocked: {achievements.unlocked.length}</p>
|
|
56
|
+
|
|
57
|
+
{/* Floating badges button */}
|
|
58
|
+
<BadgesButton
|
|
59
|
+
position="bottom-right"
|
|
60
|
+
onClick={() => setIsModalOpen(true)}
|
|
61
|
+
unlockedAchievements={achievements.unlocked}
|
|
62
|
+
/>
|
|
63
|
+
|
|
64
|
+
{/* Achievement history modal */}
|
|
65
|
+
<BadgesModal
|
|
66
|
+
isOpen={isModalOpen}
|
|
67
|
+
onClose={() => setIsModalOpen(false)}
|
|
68
|
+
achievements={achievements.unlocked}
|
|
69
|
+
/>
|
|
70
|
+
</div>
|
|
71
|
+
);
|
|
72
|
+
};
|
|
73
|
+
|
|
74
|
+
// Root component with provider
|
|
75
|
+
const App = () => {
|
|
76
|
+
return (
|
|
77
|
+
<AchievementProvider
|
|
78
|
+
achievements={achievementConfig}
|
|
79
|
+
storage="local"
|
|
80
|
+
>
|
|
81
|
+
<DemoComponent />
|
|
82
|
+
</AchievementProvider>
|
|
83
|
+
);
|
|
84
|
+
};
|
|
85
|
+
|
|
86
|
+
export default App;
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
When you click "Score 100 points":
|
|
90
|
+
1. A toast notification appears
|
|
91
|
+
2. Confetti animation plays
|
|
92
|
+
3. The achievement is stored and visible in the badges modal
|
|
93
|
+
4. The badges button updates to show the new count
|
|
94
|
+
|
|
5
95
|
## State Management Options
|
|
6
96
|
|
|
7
97
|
This package includes example implementations for different state management solutions in the `stories/examples` directory:
|
|
@@ -22,6 +112,41 @@ See the [examples directory](./stories/examples) for detailed implementations an
|
|
|
22
112
|
- Confetti animations
|
|
23
113
|
- TypeScript support
|
|
24
114
|
|
|
115
|
+
## Achievement Notifications & History
|
|
116
|
+
|
|
117
|
+
The package provides two ways to display achievements to users:
|
|
118
|
+
|
|
119
|
+
### Automatic Notifications
|
|
120
|
+
When an achievement is unlocked, the system automatically:
|
|
121
|
+
- Shows a toast notification in the top-right corner with the achievement details
|
|
122
|
+
- Plays a confetti animation to celebrate the achievement
|
|
123
|
+
|
|
124
|
+
These notifications appear immediately when achievements are unlocked and require no additional setup.
|
|
125
|
+
|
|
126
|
+
### Achievement History
|
|
127
|
+
To allow users to view their achievement history, the package provides two essential components:
|
|
128
|
+
|
|
129
|
+
1. `BadgesButton`: A floating button that shows the number of unlocked achievements
|
|
130
|
+
```tsx
|
|
131
|
+
<BadgesButton
|
|
132
|
+
position="bottom-right" // or "top-right", "top-left", "bottom-left"
|
|
133
|
+
onClick={() => setIsModalOpen(true)}
|
|
134
|
+
unlockedAchievements={achievements.unlocked}
|
|
135
|
+
/>
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
2. `BadgesModal`: A modal dialog that displays all unlocked achievements with their details
|
|
139
|
+
```tsx
|
|
140
|
+
<BadgesModal
|
|
141
|
+
isOpen={isModalOpen}
|
|
142
|
+
onClose={() => setIsModalOpen(false)}
|
|
143
|
+
achievements={achievements.unlocked}
|
|
144
|
+
icons={customIcons} // Optional custom icons
|
|
145
|
+
/>
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
These components are the recommended way to give users access to their achievement history. While you could build custom UI using the `useAchievements` hook data, these components provide a polished, ready-to-use interface for achievement history.
|
|
149
|
+
|
|
25
150
|
## Installation
|
|
26
151
|
|
|
27
152
|
```bash
|