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.
Files changed (54) hide show
  1. package/README.md +354 -21
  2. package/dist/index.d.ts +210 -2
  3. package/dist/index.js +915 -185
  4. package/dist/index.js.map +1 -1
  5. package/dist/types/core/components/BadgesButton.d.ts +18 -3
  6. package/dist/types/core/components/BadgesModal.d.ts +4 -1
  7. package/dist/types/core/hooks/useWindowSize.d.ts +16 -0
  8. package/dist/types/core/types.d.ts +6 -0
  9. package/dist/types/core/ui/BuiltInConfetti.d.ts +7 -0
  10. package/dist/types/core/ui/BuiltInModal.d.ts +7 -0
  11. package/dist/types/core/ui/BuiltInNotification.d.ts +7 -0
  12. package/dist/types/core/ui/LegacyWrappers.d.ts +21 -0
  13. package/dist/types/core/ui/interfaces.d.ts +131 -0
  14. package/dist/types/core/ui/legacyDetector.d.ts +40 -0
  15. package/dist/types/core/ui/themes.d.ts +14 -0
  16. package/dist/types/hooks/useSimpleAchievements.d.ts +5 -0
  17. package/dist/types/index.d.ts +6 -1
  18. package/dist/types/providers/AchievementProvider.d.ts +15 -2
  19. package/package.json +15 -1
  20. package/dist/assets/defaultIcons.d.ts +0 -81
  21. package/dist/badges.d.ts +0 -8
  22. package/dist/components/Achievement.d.ts +0 -10
  23. package/dist/components/AchievementModal.d.ts +0 -12
  24. package/dist/components/Badge.d.ts +0 -9
  25. package/dist/components/BadgesButton.d.ts +0 -14
  26. package/dist/components/BadgesModal.d.ts +0 -12
  27. package/dist/components/ConfettiWrapper.d.ts +0 -6
  28. package/dist/components/Progress.d.ts +0 -6
  29. package/dist/context/AchievementContext.d.ts +0 -21
  30. package/dist/defaultStyles.d.ts +0 -19
  31. package/dist/hooks/useAchievement.d.ts +0 -8
  32. package/dist/hooks/useAchievementState.d.ts +0 -4
  33. package/dist/index.cjs.js +0 -2428
  34. package/dist/index.esm.js +0 -2403
  35. package/dist/levels.d.ts +0 -7
  36. package/dist/providers/AchievementProvider.d.ts +0 -12
  37. package/dist/redux/achievementSlice.d.ts +0 -30
  38. package/dist/redux/notificationSlice.d.ts +0 -7
  39. package/dist/redux/store.d.ts +0 -15
  40. package/dist/stories/Button.d.ts +0 -28
  41. package/dist/stories/Button.stories.d.ts +0 -23
  42. package/dist/stories/Header.d.ts +0 -13
  43. package/dist/stories/Header.stories.d.ts +0 -18
  44. package/dist/stories/Page.d.ts +0 -3
  45. package/dist/stories/Page.stories.d.ts +0 -12
  46. package/dist/types/core/context/AchievementContext.d.ts +0 -5
  47. package/dist/types/stories/Button.d.ts +0 -16
  48. package/dist/types/stories/Button.stories.d.ts +0 -23
  49. package/dist/types/stories/Header.d.ts +0 -13
  50. package/dist/types/stories/Header.stories.d.ts +0 -18
  51. package/dist/types/stories/Page.d.ts +0 -3
  52. package/dist/types/stories/Page.stories.d.ts +0 -12
  53. package/dist/types.d.ts +0 -37
  54. 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 react react-dom react-confetti react-modal react-toastify react-use
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
- Note: React and React DOM should be version 16.8.0 or higher. If you already have some of these packages installed, npm will skip them automatically.
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 new three-tier Builder API - 95% less code!
50
+ // Define achievements with the Builder API for easy configuration
31
51
  import { AchievementBuilder } from 'react-achievements';
32
52
 
33
- // Simple achievements with the new Simple API
34
- const gameAchievements = {
35
- score: {
36
- 100: { title: 'Century!', description: 'Score 100 points', icon: '🏆' },
37
- 500: { title: 'High Scorer!', description: 'Score 500 points', icon: '⭐' }
38
- },
39
- level: {
40
- 5: { title: 'Leveling Up', description: 'Reach level 5', icon: '📈' }
41
- },
42
- completedTutorial: {
43
- true: { title: 'Tutorial Master', description: 'Complete the tutorial', icon: '📚' }
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
- buttonClicks: {
46
- 10: { title: 'Clicker', description: 'Click 10 times', icon: '👆' },
47
- 100: { title: 'Super Clicker', description: 'Click 100 times', icon: '🖱️' }
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
- position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
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
- export { AchievementBuilder, AchievementCondition, AchievementConfiguration, AchievementConfigurationType, AchievementContext, AchievementContextValue, AchievementDetails, AchievementError, AchievementMetricArrayValue, AchievementMetricValue, AchievementMetrics, AchievementProvider, AchievementProviderProps$1 as AchievementProviderProps, AchievementState, AchievementStorage, AnyAchievementStorage, AsyncAchievementStorage, AsyncStorageAdapter, AwardDetails, BadgesButton, BadgesModal, ConfettiWrapper, ConfigurationError, CustomAchievementDetails, ExportedData, ImportOptions, ImportResult, ImportValidationError, IndexedDBStorage, InitialAchievementMetrics, LocalStorage, MemoryStorage, OfflineQueueStorage, RestApiStorage, RestApiStorageConfig, SimpleAchievementConfig, SimpleAchievementDetails, StorageError, StorageQuotaError, StorageType, StylesProps, SyncError, createConfigHash, defaultAchievementIcons, defaultStyles, exportAchievementData, importAchievementData, isAchievementError, isAsyncStorage, isRecoverableError, isSimpleConfig, normalizeAchievements, useAchievements, useSimpleAchievements };
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 };