react-achievements 3.4.2 → 3.6.0
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 +354 -21
- package/dist/index.d.ts +210 -2
- package/dist/index.js +915 -185
- package/dist/index.js.map +1 -1
- package/dist/types/core/components/BadgesButton.d.ts +18 -3
- package/dist/types/core/components/BadgesModal.d.ts +4 -1
- package/dist/types/core/hooks/useWindowSize.d.ts +16 -0
- package/dist/types/core/types.d.ts +6 -0
- package/dist/types/core/ui/BuiltInConfetti.d.ts +7 -0
- package/dist/types/core/ui/BuiltInModal.d.ts +7 -0
- package/dist/types/core/ui/BuiltInNotification.d.ts +7 -0
- package/dist/types/core/ui/LegacyWrappers.d.ts +21 -0
- package/dist/types/core/ui/interfaces.d.ts +131 -0
- package/dist/types/core/ui/legacyDetector.d.ts +40 -0
- package/dist/types/core/ui/themes.d.ts +14 -0
- package/dist/types/hooks/useSimpleAchievements.d.ts +5 -0
- package/dist/types/index.d.ts +6 -1
- package/dist/types/providers/AchievementProvider.d.ts +15 -2
- package/package.json +15 -1
- package/dist/assets/defaultIcons.d.ts +0 -81
- package/dist/badges.d.ts +0 -8
- package/dist/components/Achievement.d.ts +0 -10
- package/dist/components/AchievementModal.d.ts +0 -12
- package/dist/components/Badge.d.ts +0 -9
- package/dist/components/BadgesButton.d.ts +0 -14
- package/dist/components/BadgesModal.d.ts +0 -12
- package/dist/components/ConfettiWrapper.d.ts +0 -6
- package/dist/components/Progress.d.ts +0 -6
- package/dist/context/AchievementContext.d.ts +0 -21
- package/dist/defaultStyles.d.ts +0 -19
- package/dist/hooks/useAchievement.d.ts +0 -8
- package/dist/hooks/useAchievementState.d.ts +0 -4
- package/dist/index.cjs.js +0 -2428
- package/dist/index.esm.js +0 -2403
- package/dist/levels.d.ts +0 -7
- package/dist/providers/AchievementProvider.d.ts +0 -12
- package/dist/redux/achievementSlice.d.ts +0 -30
- package/dist/redux/notificationSlice.d.ts +0 -7
- package/dist/redux/store.d.ts +0 -15
- package/dist/stories/Button.d.ts +0 -28
- package/dist/stories/Button.stories.d.ts +0 -23
- package/dist/stories/Header.d.ts +0 -13
- package/dist/stories/Header.stories.d.ts +0 -18
- package/dist/stories/Page.d.ts +0 -3
- package/dist/stories/Page.stories.d.ts +0 -12
- package/dist/types/core/context/AchievementContext.d.ts +0 -5
- package/dist/types/stories/Button.d.ts +0 -16
- package/dist/types/stories/Button.stories.d.ts +0 -23
- package/dist/types/stories/Header.d.ts +0 -13
- package/dist/types/stories/Header.stories.d.ts +0 -18
- package/dist/types/stories/Page.d.ts +0 -3
- package/dist/types/stories/Page.stories.d.ts +0 -12
- package/dist/types.d.ts +0 -37
- package/dist/utils/EventEmitter.d.ts +0 -6
package/README.md
CHANGED
|
@@ -8,11 +8,31 @@ A flexible and extensible achievement system for React applications. This packag
|
|
|
8
8
|
|
|
9
9
|
## Installation
|
|
10
10
|
|
|
11
|
+
**NEW in v3.6.0**: Optional built-in UI system available! Choose between the traditional external dependencies or the new lightweight built-in UI.
|
|
12
|
+
|
|
13
|
+
### Option 1: Traditional External UI (Default)
|
|
14
|
+
```bash
|
|
15
|
+
npm install react-achievements react-confetti react-modal react-toastify react-use
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
### Option 2: Built-in UI (NEW - Opt-in)
|
|
11
19
|
```bash
|
|
12
|
-
npm install react-achievements
|
|
20
|
+
npm install react-achievements
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Then explicitly enable built-in UI in your code:
|
|
24
|
+
```tsx
|
|
25
|
+
<AchievementProvider
|
|
26
|
+
achievements={config}
|
|
27
|
+
useBuiltInUI={true} // Required to use built-in UI
|
|
28
|
+
>
|
|
29
|
+
<YourApp />
|
|
30
|
+
</AchievementProvider>
|
|
13
31
|
```
|
|
14
32
|
|
|
15
|
-
|
|
33
|
+
**Requirements**: React 16.8+ and react-dom are required (defined as peerDependencies).
|
|
34
|
+
|
|
35
|
+
**Note**: To maintain backwards compatibility, v3.6.0 defaults to external UI dependencies. The built-in UI system is opt-in via the `useBuiltInUI` prop. In v4.0.0, built-in UI will become the default. See the [Built-in UI System](#built-in-ui-system-new-in-v360) section below.
|
|
16
36
|
|
|
17
37
|
## Quick Start
|
|
18
38
|
|
|
@@ -27,26 +47,40 @@ import {
|
|
|
27
47
|
BadgesModal
|
|
28
48
|
} from 'react-achievements';
|
|
29
49
|
|
|
30
|
-
// Define achievements with the
|
|
50
|
+
// Define achievements with the Builder API for easy configuration
|
|
31
51
|
import { AchievementBuilder } from 'react-achievements';
|
|
32
52
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
53
|
+
const gameAchievements = AchievementBuilder.combine([
|
|
54
|
+
// Score achievements with custom awards
|
|
55
|
+
AchievementBuilder.createScoreAchievement(100)
|
|
56
|
+
.withAward({ title: 'Century!', description: 'Score 100 points', icon: '🏆' }),
|
|
57
|
+
AchievementBuilder.createScoreAchievement(500)
|
|
58
|
+
.withAward({ title: 'High Scorer!', description: 'Score 500 points', icon: '⭐' }),
|
|
59
|
+
|
|
60
|
+
// Level achievement
|
|
61
|
+
AchievementBuilder.createLevelAchievement(5)
|
|
62
|
+
.withAward({ title: 'Leveling Up', description: 'Reach level 5', icon: '📈' }),
|
|
63
|
+
|
|
64
|
+
// Boolean achievement
|
|
65
|
+
AchievementBuilder.createBooleanAchievement('completedTutorial')
|
|
66
|
+
.withAward({ title: 'Tutorial Master', description: 'Complete the tutorial', icon: '📚' }),
|
|
67
|
+
|
|
68
|
+
// For custom numeric metrics, use Simple API syntax (easiest)
|
|
69
|
+
{
|
|
70
|
+
buttonClicks: {
|
|
71
|
+
10: { title: 'Clicker', description: 'Click 10 times', icon: '👆' },
|
|
72
|
+
100: { title: 'Super Clicker', description: 'Click 100 times', icon: '🖱️' }
|
|
73
|
+
}
|
|
44
74
|
},
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
75
|
+
|
|
76
|
+
// Or use the full builder for complex conditions (Tier 3)
|
|
77
|
+
AchievementBuilder.create()
|
|
78
|
+
.withId('speed_demon')
|
|
79
|
+
.withMetric('buttonClicks')
|
|
80
|
+
.withCondition((clicks) => typeof clicks === 'number' && clicks >= 50)
|
|
81
|
+
.withAward({ title: 'Speed Demon', description: 'Click 50 times quickly', icon: '⚡' })
|
|
82
|
+
.build()
|
|
83
|
+
]);
|
|
50
84
|
|
|
51
85
|
// Demo component with all essential features
|
|
52
86
|
const DemoComponent = () => {
|
|
@@ -121,10 +155,262 @@ export default App;
|
|
|
121
155
|
|
|
122
156
|
When you click "Score 100 points":
|
|
123
157
|
1. A toast notification appears automatically
|
|
124
|
-
2. Confetti animation plays
|
|
158
|
+
2. Confetti animation plays
|
|
125
159
|
3. The achievement is stored and visible in the badges modal
|
|
126
160
|
4. The badges button updates to show the new count
|
|
127
161
|
|
|
162
|
+
## Built-in UI System (NEW in v3.6.0)
|
|
163
|
+
|
|
164
|
+
React Achievements v3.6.0 introduces a modern, lightweight UI system with **zero external dependencies**. The built-in components provide beautiful notifications, modals, and confetti animations with full theme customization.
|
|
165
|
+
|
|
166
|
+
### Key Benefits
|
|
167
|
+
|
|
168
|
+
- **Modern Design**: Sleek gradients, smooth animations, and polished components
|
|
169
|
+
- **Theme System**: 3 built-in themes (modern, minimal, gamified)
|
|
170
|
+
- **Component Injection**: Replace any UI component with your own implementation
|
|
171
|
+
- **Backwards Compatible**: Existing apps work without changes
|
|
172
|
+
- **SSR Safe**: Proper window checks for server-side rendering
|
|
173
|
+
- **Lightweight**: Built-in UI with zero external dependencies
|
|
174
|
+
|
|
175
|
+
### Quick Migration
|
|
176
|
+
|
|
177
|
+
**To use built-in UI** - opt-in with the `useBuiltInUI` prop:
|
|
178
|
+
```tsx
|
|
179
|
+
<AchievementProvider
|
|
180
|
+
achievements={config}
|
|
181
|
+
useBuiltInUI={true} // Force built-in UI, ignore external dependencies
|
|
182
|
+
>
|
|
183
|
+
<YourApp />
|
|
184
|
+
</AchievementProvider>
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### Built-in Theme Presets
|
|
188
|
+
|
|
189
|
+
Choose from 3 professionally designed themes:
|
|
190
|
+
|
|
191
|
+
#### Modern Theme (Default)
|
|
192
|
+
```tsx
|
|
193
|
+
<AchievementProvider
|
|
194
|
+
achievements={config}
|
|
195
|
+
useBuiltInUI={true}
|
|
196
|
+
ui={{ theme: 'modern' }}
|
|
197
|
+
>
|
|
198
|
+
```
|
|
199
|
+
- Dark gradients with smooth animations
|
|
200
|
+
- Green accent colors
|
|
201
|
+
- Professional and polished look
|
|
202
|
+
- Perfect for productivity apps and games
|
|
203
|
+
|
|
204
|
+
#### Minimal Theme
|
|
205
|
+
```tsx
|
|
206
|
+
<AchievementProvider
|
|
207
|
+
achievements={config}
|
|
208
|
+
useBuiltInUI={true}
|
|
209
|
+
ui={{ theme: 'minimal' }}
|
|
210
|
+
>
|
|
211
|
+
```
|
|
212
|
+
- Light, clean design
|
|
213
|
+
- Subtle shadows and simple borders
|
|
214
|
+
- Reduced motion for accessibility
|
|
215
|
+
- Perfect for professional and corporate apps
|
|
216
|
+
|
|
217
|
+
#### Gamified Theme
|
|
218
|
+
```tsx
|
|
219
|
+
<AchievementProvider
|
|
220
|
+
achievements={config}
|
|
221
|
+
useBuiltInUI={true}
|
|
222
|
+
ui={{ theme: 'gamified' }}
|
|
223
|
+
>
|
|
224
|
+
```
|
|
225
|
+
- Perfect for games and engaging experiences
|
|
226
|
+
- Badges instead of rectangular displays
|
|
227
|
+
|
|
228
|
+
### Notification Positions
|
|
229
|
+
|
|
230
|
+
Place notifications anywhere on screen:
|
|
231
|
+
|
|
232
|
+
```tsx
|
|
233
|
+
<AchievementProvider
|
|
234
|
+
achievements={config}
|
|
235
|
+
useBuiltInUI={true}
|
|
236
|
+
ui={{
|
|
237
|
+
theme: 'modern',
|
|
238
|
+
notificationPosition: 'top-center', // Default
|
|
239
|
+
// Options: 'top-left', 'top-center', 'top-right',
|
|
240
|
+
// 'bottom-left', 'bottom-center', 'bottom-right'
|
|
241
|
+
}}
|
|
242
|
+
>
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
### Custom Component Injection
|
|
246
|
+
|
|
247
|
+
For advanced users who need full customization beyond the 3 built-in themes, you can replace any UI component with your own implementation:
|
|
248
|
+
|
|
249
|
+
```tsx
|
|
250
|
+
import { AchievementProvider, NotificationProps } from 'react-achievements';
|
|
251
|
+
|
|
252
|
+
// Create your custom notification component
|
|
253
|
+
const MyCustomNotification: React.FC<NotificationProps> = ({
|
|
254
|
+
achievement,
|
|
255
|
+
onClose,
|
|
256
|
+
duration,
|
|
257
|
+
}) => {
|
|
258
|
+
useEffect(() => {
|
|
259
|
+
const timer = setTimeout(onClose, duration);
|
|
260
|
+
return () => clearTimeout(timer);
|
|
261
|
+
}, [duration, onClose]);
|
|
262
|
+
|
|
263
|
+
return (
|
|
264
|
+
<div className="my-custom-notification">
|
|
265
|
+
<h3>{achievement.title}</h3>
|
|
266
|
+
<p>{achievement.description}</p>
|
|
267
|
+
<span>{achievement.icon}</span>
|
|
268
|
+
</div>
|
|
269
|
+
);
|
|
270
|
+
};
|
|
271
|
+
|
|
272
|
+
// Inject your component
|
|
273
|
+
<AchievementProvider
|
|
274
|
+
achievements={config}
|
|
275
|
+
ui={{
|
|
276
|
+
NotificationComponent: MyCustomNotification,
|
|
277
|
+
// ModalComponent: MyCustomModal, // Optional
|
|
278
|
+
// ConfettiComponent: MyCustomConfetti, // Optional
|
|
279
|
+
}}
|
|
280
|
+
>
|
|
281
|
+
<YourApp />
|
|
282
|
+
</AchievementProvider>
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
### BadgesButton Placement Modes
|
|
286
|
+
|
|
287
|
+
**NEW**: BadgesButton now supports both fixed positioning and inline mode:
|
|
288
|
+
|
|
289
|
+
#### Fixed Positioning (Default)
|
|
290
|
+
Traditional floating button:
|
|
291
|
+
```tsx
|
|
292
|
+
import { BadgesButton } from 'react-achievements';
|
|
293
|
+
|
|
294
|
+
<BadgesButton
|
|
295
|
+
placement="fixed" // Default
|
|
296
|
+
position="bottom-right" // Corner position
|
|
297
|
+
onClick={() => setModalOpen(true)}
|
|
298
|
+
unlockedAchievements={achievements}
|
|
299
|
+
/>
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
#### Inline Mode (NEW)
|
|
303
|
+
Embed the badge button in drawers, navbars, sidebars:
|
|
304
|
+
```tsx
|
|
305
|
+
function MyDrawer() {
|
|
306
|
+
const [modalOpen, setModalOpen] = useState(false);
|
|
307
|
+
|
|
308
|
+
return (
|
|
309
|
+
<Drawer>
|
|
310
|
+
<nav>
|
|
311
|
+
<NavItem>Home</NavItem>
|
|
312
|
+
<NavItem>Settings</NavItem>
|
|
313
|
+
|
|
314
|
+
{/* Badge button inside drawer - no fixed positioning */}
|
|
315
|
+
<BadgesButton
|
|
316
|
+
placement="inline"
|
|
317
|
+
onClick={() => setModalOpen(true)}
|
|
318
|
+
unlockedAchievements={achievements}
|
|
319
|
+
theme="modern" // Matches your app theme
|
|
320
|
+
/>
|
|
321
|
+
</nav>
|
|
322
|
+
</Drawer>
|
|
323
|
+
);
|
|
324
|
+
}
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
**Inline mode benefits:**
|
|
328
|
+
- Works in drawers, sidebars, navigation bars
|
|
329
|
+
- Flows with your layout (no fixed positioning)
|
|
330
|
+
- Themeable to match surrounding UI
|
|
331
|
+
- Fully customizable with `styles` prop
|
|
332
|
+
|
|
333
|
+
### UI Configuration Options
|
|
334
|
+
|
|
335
|
+
Complete UI configuration reference:
|
|
336
|
+
|
|
337
|
+
```tsx
|
|
338
|
+
<AchievementProvider
|
|
339
|
+
achievements={config}
|
|
340
|
+
useBuiltInUI={true}
|
|
341
|
+
ui={{
|
|
342
|
+
// Theme configuration
|
|
343
|
+
theme: 'modern', // 'modern' | 'minimal' | 'gamified' | custom theme name
|
|
344
|
+
|
|
345
|
+
// Component overrides
|
|
346
|
+
NotificationComponent: MyCustomNotification, // Optional
|
|
347
|
+
ModalComponent: MyCustomModal, // Optional
|
|
348
|
+
ConfettiComponent: MyCustomConfetti, // Optional
|
|
349
|
+
|
|
350
|
+
// Notification settings
|
|
351
|
+
notificationPosition: 'top-center', // Position on screen
|
|
352
|
+
enableNotifications: true, // Default: true
|
|
353
|
+
|
|
354
|
+
// Confetti settings
|
|
355
|
+
enableConfetti: true, // Default: true
|
|
356
|
+
|
|
357
|
+
// Direct theme object (bypasses registry)
|
|
358
|
+
customTheme: {
|
|
359
|
+
name: 'inline-theme',
|
|
360
|
+
notification: { /* ... */ },
|
|
361
|
+
modal: { /* ... */ },
|
|
362
|
+
confetti: { /* ... */ },
|
|
363
|
+
},
|
|
364
|
+
}}
|
|
365
|
+
>
|
|
366
|
+
<YourApp />
|
|
367
|
+
</AchievementProvider>
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
### Migration Guide
|
|
371
|
+
|
|
372
|
+
#### Existing Users (v3.5.0 and earlier)
|
|
373
|
+
|
|
374
|
+
**Option 1: No changes (keep using external dependencies)**
|
|
375
|
+
- Your code works exactly as before
|
|
376
|
+
- You'll see a deprecation warning in console (once per session)
|
|
377
|
+
- Plan to migrate before v4.0.0
|
|
378
|
+
|
|
379
|
+
**Option 2: Migrate to built-in UI**
|
|
380
|
+
1. Add `useBuiltInUI={true}` to your AchievementProvider
|
|
381
|
+
2. Test your app (UI will change to modern theme)
|
|
382
|
+
3. Optionally customize with `ui={{ theme: 'minimal' }}` if you prefer lighter styling
|
|
383
|
+
4. Remove external dependencies:
|
|
384
|
+
```bash
|
|
385
|
+
npm uninstall react-toastify react-modal react-confetti react-use
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
#### New Projects
|
|
389
|
+
|
|
390
|
+
For new projects using built-in UI, install react-achievements and explicitly opt-in:
|
|
391
|
+
|
|
392
|
+
```bash
|
|
393
|
+
npm install react-achievements
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
```tsx
|
|
397
|
+
<AchievementProvider
|
|
398
|
+
achievements={config}
|
|
399
|
+
useBuiltInUI={true} // Explicitly enable built-in UI
|
|
400
|
+
ui={{ theme: 'modern' }} // Optional theme customization
|
|
401
|
+
>
|
|
402
|
+
{/* Beautiful built-in UI */}
|
|
403
|
+
</AchievementProvider>
|
|
404
|
+
```
|
|
405
|
+
|
|
406
|
+
Without `useBuiltInUI={true}`, you'll need to install the external UI dependencies (default behavior for v3.6.0).
|
|
407
|
+
|
|
408
|
+
### Deprecation Timeline
|
|
409
|
+
|
|
410
|
+
- **v3.6.0 (current)**: Built-in UI available, external deps optional with deprecation warning
|
|
411
|
+
- **v3.7.0-v3.9.0**: Continued support for both systems, refinements based on feedback
|
|
412
|
+
- **v4.0.0**: External dependencies fully optional, built-in UI becomes default
|
|
413
|
+
|
|
128
414
|
## Simple API (Recommended)
|
|
129
415
|
|
|
130
416
|
Perfect for 90% of use cases - threshold-based achievements with minimal configuration:
|
|
@@ -322,6 +608,10 @@ See the [examples directory](./stories/examples) for detailed implementations an
|
|
|
322
608
|
- Toast notifications
|
|
323
609
|
- Confetti animations
|
|
324
610
|
- TypeScript support
|
|
611
|
+
- **NEW in v3.6.0**: Built-in UI components with zero external dependencies
|
|
612
|
+
- **NEW in v3.6.0**: Extensible theme system with 3 built-in themes (modern, minimal, gamified)
|
|
613
|
+
- **NEW in v3.6.0**: Component injection for full UI customization
|
|
614
|
+
- **NEW in v3.6.0**: BadgesButton inline mode for drawers and sidebars
|
|
325
615
|
- **NEW in v3.4.0**: Async storage support (IndexedDB, REST API, Offline Queue)
|
|
326
616
|
- **NEW in v3.4.0**: 50MB+ storage capacity with IndexedDB
|
|
327
617
|
- **NEW in v3.4.0**: Server-side sync with REST API storage
|
|
@@ -354,8 +644,10 @@ To allow users to view their achievement history, the package provides two essen
|
|
|
354
644
|
```
|
|
355
645
|
|
|
356
646
|
2. `BadgesModal`: A modal dialog that displays all unlocked achievements with their details
|
|
647
|
+
|
|
648
|
+
**Basic Usage** (shows only unlocked achievements):
|
|
357
649
|
```tsx
|
|
358
|
-
<BadgesModal
|
|
650
|
+
<BadgesModal
|
|
359
651
|
isOpen={isModalOpen}
|
|
360
652
|
onClose={() => setIsModalOpen(false)}
|
|
361
653
|
achievements={achievements.unlocked}
|
|
@@ -363,6 +655,47 @@ To allow users to view their achievement history, the package provides two essen
|
|
|
363
655
|
/>
|
|
364
656
|
```
|
|
365
657
|
|
|
658
|
+
**Show All Achievements** (NEW in v3.5.0): Display both locked and unlocked achievements to motivate users and show them what's available:
|
|
659
|
+
|
|
660
|
+
```tsx
|
|
661
|
+
import { useAchievements, BadgesModal } from 'react-achievements';
|
|
662
|
+
|
|
663
|
+
function MyComponent() {
|
|
664
|
+
const { getAllAchievements } = useAchievements();
|
|
665
|
+
const [isModalOpen, setIsModalOpen] = useState(false);
|
|
666
|
+
|
|
667
|
+
// Get all achievements with their unlock status
|
|
668
|
+
const allAchievements = getAllAchievements();
|
|
669
|
+
|
|
670
|
+
return (
|
|
671
|
+
<BadgesModal
|
|
672
|
+
isOpen={isModalOpen}
|
|
673
|
+
onClose={() => setIsModalOpen(false)}
|
|
674
|
+
showAllAchievements={true} // Enable showing locked achievements
|
|
675
|
+
showUnlockConditions={true} // Show hints on how to unlock
|
|
676
|
+
allAchievements={allAchievements} // Pass all achievements with status
|
|
677
|
+
/>
|
|
678
|
+
);
|
|
679
|
+
}
|
|
680
|
+
```
|
|
681
|
+
|
|
682
|
+
**Props for Show All Achievements:**
|
|
683
|
+
- `showAllAchievements` (boolean): When `true`, displays both locked and unlocked achievements. Default: `false`
|
|
684
|
+
- `showUnlockConditions` (boolean): When `true`, shows unlock requirement hints for locked achievements. Default: `false`
|
|
685
|
+
- `allAchievements` (AchievementWithStatus[]): Array of all achievements with their `isUnlocked` status
|
|
686
|
+
|
|
687
|
+
**Visual Features:**
|
|
688
|
+
- Locked achievements appear grayed out with reduced opacity
|
|
689
|
+
- Lock icon (🔒) displayed on locked achievements
|
|
690
|
+
- Optional unlock condition hints guide users on how to progress
|
|
691
|
+
- Fully customizable via the style system
|
|
692
|
+
|
|
693
|
+
**Use Cases:**
|
|
694
|
+
- Show users a roadmap of available achievements
|
|
695
|
+
- Motivate progression by revealing future rewards
|
|
696
|
+
- Provide clear guidance on unlock requirements
|
|
697
|
+
- Create achievement-based progression systems
|
|
698
|
+
|
|
366
699
|
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.
|
|
367
700
|
|
|
368
701
|
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,135 @@
|
|
|
1
1
|
import React$1 from 'react';
|
|
2
2
|
|
|
3
|
+
/**
|
|
4
|
+
* Notification component interface
|
|
5
|
+
* Displays achievement unlock notifications
|
|
6
|
+
*/
|
|
7
|
+
interface NotificationProps {
|
|
8
|
+
achievement: {
|
|
9
|
+
id: string;
|
|
10
|
+
title: string;
|
|
11
|
+
description: string;
|
|
12
|
+
icon: string;
|
|
13
|
+
};
|
|
14
|
+
onClose?: () => void;
|
|
15
|
+
duration?: number;
|
|
16
|
+
position?: NotificationPosition;
|
|
17
|
+
theme?: string;
|
|
18
|
+
}
|
|
19
|
+
type NotificationComponent = React$1.FC<NotificationProps>;
|
|
20
|
+
/**
|
|
21
|
+
* Modal component interface
|
|
22
|
+
* Displays list of achievements (locked/unlocked)
|
|
23
|
+
*/
|
|
24
|
+
interface ModalProps {
|
|
25
|
+
isOpen: boolean;
|
|
26
|
+
onClose: () => void;
|
|
27
|
+
achievements: AchievementWithStatus[];
|
|
28
|
+
icons?: Record<string, string>;
|
|
29
|
+
theme?: string;
|
|
30
|
+
}
|
|
31
|
+
type ModalComponent = React$1.FC<ModalProps>;
|
|
32
|
+
/**
|
|
33
|
+
* Confetti component interface
|
|
34
|
+
* Displays celebration animation
|
|
35
|
+
*/
|
|
36
|
+
interface ConfettiProps {
|
|
37
|
+
show: boolean;
|
|
38
|
+
duration?: number;
|
|
39
|
+
particleCount?: number;
|
|
40
|
+
colors?: string[];
|
|
41
|
+
}
|
|
42
|
+
type ConfettiComponent = React$1.FC<ConfettiProps>;
|
|
43
|
+
/**
|
|
44
|
+
* Notification positioning options
|
|
45
|
+
*/
|
|
46
|
+
type NotificationPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
|
|
47
|
+
/**
|
|
48
|
+
* Theme configuration interface
|
|
49
|
+
* Defines styling for all UI components
|
|
50
|
+
*/
|
|
51
|
+
interface ThemeConfig {
|
|
52
|
+
name: string;
|
|
53
|
+
notification: {
|
|
54
|
+
background: string;
|
|
55
|
+
textColor: string;
|
|
56
|
+
accentColor: string;
|
|
57
|
+
borderRadius: string;
|
|
58
|
+
boxShadow: string;
|
|
59
|
+
fontSize?: {
|
|
60
|
+
header?: string;
|
|
61
|
+
title?: string;
|
|
62
|
+
description?: string;
|
|
63
|
+
};
|
|
64
|
+
};
|
|
65
|
+
modal: {
|
|
66
|
+
overlayColor: string;
|
|
67
|
+
background: string;
|
|
68
|
+
textColor: string;
|
|
69
|
+
accentColor: string;
|
|
70
|
+
borderRadius: string;
|
|
71
|
+
headerFontSize?: string;
|
|
72
|
+
achievementCardBorderRadius?: string;
|
|
73
|
+
achievementLayout?: 'horizontal' | 'badge';
|
|
74
|
+
};
|
|
75
|
+
confetti: {
|
|
76
|
+
colors: string[];
|
|
77
|
+
particleCount: number;
|
|
78
|
+
shapes?: ('circle' | 'square')[];
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* UI Configuration for AchievementProvider
|
|
83
|
+
* Allows customization of all UI components
|
|
84
|
+
*/
|
|
85
|
+
interface UIConfig {
|
|
86
|
+
/**
|
|
87
|
+
* Custom notification component
|
|
88
|
+
* If not provided, uses built-in or legacy component based on detection
|
|
89
|
+
*/
|
|
90
|
+
NotificationComponent?: NotificationComponent;
|
|
91
|
+
/**
|
|
92
|
+
* Custom modal component
|
|
93
|
+
* If not provided, uses built-in or legacy component based on detection
|
|
94
|
+
*/
|
|
95
|
+
ModalComponent?: ModalComponent;
|
|
96
|
+
/**
|
|
97
|
+
* Custom confetti component
|
|
98
|
+
* If not provided, uses built-in or legacy component based on detection
|
|
99
|
+
*/
|
|
100
|
+
ConfettiComponent?: ConfettiComponent;
|
|
101
|
+
/**
|
|
102
|
+
* Theme to use (built-in name or registered custom theme name)
|
|
103
|
+
* Built-in themes: 'modern' (default), 'minimal', 'gamified'
|
|
104
|
+
*/
|
|
105
|
+
theme?: string;
|
|
106
|
+
/**
|
|
107
|
+
* Direct theme configuration override
|
|
108
|
+
* Takes precedence over theme name
|
|
109
|
+
*/
|
|
110
|
+
customTheme?: ThemeConfig;
|
|
111
|
+
/**
|
|
112
|
+
* Notification positioning
|
|
113
|
+
* @default 'top-center'
|
|
114
|
+
*/
|
|
115
|
+
notificationPosition?: NotificationPosition;
|
|
116
|
+
/**
|
|
117
|
+
* Enable/disable notifications
|
|
118
|
+
* @default true
|
|
119
|
+
*/
|
|
120
|
+
enableNotifications?: boolean;
|
|
121
|
+
/**
|
|
122
|
+
* Enable/disable confetti animations
|
|
123
|
+
* @default true
|
|
124
|
+
*/
|
|
125
|
+
enableConfetti?: boolean;
|
|
126
|
+
/**
|
|
127
|
+
* Enable/disable modal
|
|
128
|
+
* @default true
|
|
129
|
+
*/
|
|
130
|
+
enableModal?: boolean;
|
|
131
|
+
}
|
|
132
|
+
|
|
3
133
|
type AchievementMetricValue = number | string | boolean | Date | null | undefined;
|
|
4
134
|
type AchievementMetricArrayValue = AchievementMetricValue | AchievementMetricValue[];
|
|
5
135
|
interface AchievementMetrics {
|
|
@@ -11,6 +141,9 @@ interface AchievementDetails {
|
|
|
11
141
|
achievementDescription: string;
|
|
12
142
|
achievementIconKey?: string;
|
|
13
143
|
}
|
|
144
|
+
interface AchievementWithStatus extends AchievementDetails {
|
|
145
|
+
isUnlocked: boolean;
|
|
146
|
+
}
|
|
14
147
|
interface AchievementCondition {
|
|
15
148
|
isConditionMet: (value: AchievementMetricArrayValue, state: AchievementState) => boolean;
|
|
16
149
|
achievementDetails: {
|
|
@@ -77,6 +210,8 @@ interface StylesProps {
|
|
|
77
210
|
achievementTitle?: React.CSSProperties;
|
|
78
211
|
achievementDescription?: React.CSSProperties;
|
|
79
212
|
achievementIcon?: React.CSSProperties;
|
|
213
|
+
lockIcon?: React.CSSProperties;
|
|
214
|
+
lockedAchievementItem?: React.CSSProperties;
|
|
80
215
|
};
|
|
81
216
|
}
|
|
82
217
|
interface AchievementProviderProps$1 {
|
|
@@ -321,9 +456,25 @@ declare class OfflineQueueStorage implements AsyncAchievementStorage {
|
|
|
321
456
|
|
|
322
457
|
interface BadgesButtonProps {
|
|
323
458
|
onClick: () => void;
|
|
324
|
-
|
|
459
|
+
/**
|
|
460
|
+
* Position for fixed placement mode
|
|
461
|
+
* Only used when placement='fixed'
|
|
462
|
+
*/
|
|
463
|
+
position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
|
|
464
|
+
/**
|
|
465
|
+
* Placement mode
|
|
466
|
+
* - 'fixed': Traditional floating button with fixed positioning
|
|
467
|
+
* - 'inline': Regular component that can be placed in drawers, nav bars, etc.
|
|
468
|
+
* @default 'fixed'
|
|
469
|
+
*/
|
|
470
|
+
placement?: 'fixed' | 'inline';
|
|
325
471
|
styles?: React$1.CSSProperties;
|
|
326
472
|
unlockedAchievements: AchievementDetails[];
|
|
473
|
+
/**
|
|
474
|
+
* Theme name for styling (matches notification/modal theme)
|
|
475
|
+
* @default 'modern'
|
|
476
|
+
*/
|
|
477
|
+
theme?: string;
|
|
327
478
|
}
|
|
328
479
|
declare const BadgesButton: React$1.FC<BadgesButtonProps>;
|
|
329
480
|
|
|
@@ -333,6 +484,9 @@ interface BadgesModalProps {
|
|
|
333
484
|
achievements: AchievementDetails[];
|
|
334
485
|
styles?: StylesProps['badgesModal'];
|
|
335
486
|
icons?: Record<string, string>;
|
|
487
|
+
showAllAchievements?: boolean;
|
|
488
|
+
showUnlockConditions?: boolean;
|
|
489
|
+
allAchievements?: AchievementWithStatus[];
|
|
336
490
|
}
|
|
337
491
|
declare const BadgesModal: React$1.FC<BadgesModalProps>;
|
|
338
492
|
|
|
@@ -404,6 +558,7 @@ interface AchievementContextType {
|
|
|
404
558
|
};
|
|
405
559
|
exportData: () => string;
|
|
406
560
|
importData: (jsonString: string, options?: ImportOptions) => ImportResult;
|
|
561
|
+
getAllAchievements: () => AchievementWithStatus[];
|
|
407
562
|
}
|
|
408
563
|
declare const AchievementContext: React$1.Context<AchievementContextType | undefined>;
|
|
409
564
|
interface AchievementProviderProps {
|
|
@@ -413,6 +568,19 @@ interface AchievementProviderProps {
|
|
|
413
568
|
icons?: Record<string, string>;
|
|
414
569
|
onError?: (error: AchievementError) => void;
|
|
415
570
|
restApiConfig?: RestApiStorageConfig;
|
|
571
|
+
/**
|
|
572
|
+
* UI configuration for notifications, modal, and confetti
|
|
573
|
+
* NEW in v3.6.0
|
|
574
|
+
*/
|
|
575
|
+
ui?: UIConfig;
|
|
576
|
+
/**
|
|
577
|
+
* Force use of built-in UI components (opt-in for v3.x)
|
|
578
|
+
* Set to true to skip legacy library detection and use built-in UI
|
|
579
|
+
* In v4.0.0, this will become the default behavior
|
|
580
|
+
* NEW in v3.6.0
|
|
581
|
+
* @default false
|
|
582
|
+
*/
|
|
583
|
+
useBuiltInUI?: boolean;
|
|
416
584
|
}
|
|
417
585
|
declare const AchievementProvider: React$1.FC<AchievementProviderProps>;
|
|
418
586
|
|
|
@@ -475,6 +643,11 @@ declare const useSimpleAchievements: () => {
|
|
|
475
643
|
* @returns Import result with success status and any errors
|
|
476
644
|
*/
|
|
477
645
|
importData: (jsonString: string, options?: ImportOptions) => ImportResult;
|
|
646
|
+
/**
|
|
647
|
+
* Get all achievements with their unlock status
|
|
648
|
+
* @returns Array of achievements with isUnlocked boolean property
|
|
649
|
+
*/
|
|
650
|
+
getAllAchievements: () => AchievementWithStatus[];
|
|
478
651
|
};
|
|
479
652
|
|
|
480
653
|
declare const defaultStyles: Required<StylesProps>;
|
|
@@ -659,4 +832,39 @@ declare function exportAchievementData(metrics: AchievementMetrics, unlocked: st
|
|
|
659
832
|
*/
|
|
660
833
|
declare function createConfigHash(config: any): string;
|
|
661
834
|
|
|
662
|
-
|
|
835
|
+
/**
|
|
836
|
+
* Built-in notification component
|
|
837
|
+
* Modern, theme-aware achievement notification with smooth animations
|
|
838
|
+
*/
|
|
839
|
+
declare const BuiltInNotification: React$1.FC<NotificationProps>;
|
|
840
|
+
|
|
841
|
+
/**
|
|
842
|
+
* Built-in modal component
|
|
843
|
+
* Modern, theme-aware achievement modal with smooth animations
|
|
844
|
+
*/
|
|
845
|
+
declare const BuiltInModal: React$1.FC<ModalProps>;
|
|
846
|
+
|
|
847
|
+
/**
|
|
848
|
+
* Built-in confetti component
|
|
849
|
+
* Lightweight CSS-based confetti animation
|
|
850
|
+
*/
|
|
851
|
+
declare const BuiltInConfetti: React$1.FC<ConfettiProps>;
|
|
852
|
+
|
|
853
|
+
/**
|
|
854
|
+
* Hook to track window dimensions
|
|
855
|
+
* Replacement for react-use's useWindowSize
|
|
856
|
+
*
|
|
857
|
+
* @returns Object with width and height properties
|
|
858
|
+
*
|
|
859
|
+
* @example
|
|
860
|
+
* ```tsx
|
|
861
|
+
* const { width, height } = useWindowSize();
|
|
862
|
+
* console.log(`Window size: ${width}x${height}`);
|
|
863
|
+
* ```
|
|
864
|
+
*/
|
|
865
|
+
declare function useWindowSize(): {
|
|
866
|
+
width: number;
|
|
867
|
+
height: number;
|
|
868
|
+
};
|
|
869
|
+
|
|
870
|
+
export { AchievementBuilder, AchievementCondition, AchievementConfiguration, AchievementConfigurationType, AchievementContext, AchievementContextValue, AchievementDetails, AchievementError, AchievementMetricArrayValue, AchievementMetricValue, AchievementMetrics, AchievementProvider, AchievementProviderProps$1 as AchievementProviderProps, AchievementState, AchievementStorage, AchievementWithStatus, AnyAchievementStorage, AsyncAchievementStorage, AsyncStorageAdapter, AwardDetails, BadgesButton, BadgesModal, BuiltInConfetti, BuiltInModal, BuiltInNotification, ConfettiComponent, ConfettiProps, ConfettiWrapper, ConfigurationError, CustomAchievementDetails, ExportedData, ImportOptions, ImportResult, ImportValidationError, IndexedDBStorage, InitialAchievementMetrics, LocalStorage, MemoryStorage, ModalComponent, ModalProps, NotificationComponent, NotificationPosition, NotificationProps, OfflineQueueStorage, RestApiStorage, RestApiStorageConfig, SimpleAchievementConfig, SimpleAchievementDetails, StorageError, StorageQuotaError, StorageType, StylesProps, SyncError, ThemeConfig, UIConfig, createConfigHash, defaultAchievementIcons, defaultStyles, exportAchievementData, importAchievementData, isAchievementError, isAsyncStorage, isRecoverableError, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements, useWindowSize };
|