react-achievements 3.9.3 → 4.1.0

package/README.md

@@ -1,183 +1,255 @@
 # React Achievements
 
-**Add gamification to your React app in 5 minutes** - Unlock achievements, celebrate milestones, delight users.
+**Add gamification to your React app in minutes** - Track progress, unlock achievements, show badges, and celebrate milestones.
 
-[![Demo video](https://raw.githubusercontent.com/dave-b-b/react-achievements/main/assets/achievements.png)](https://github.com/user-attachments/assets/a33fdae5-439b-4fc9-a388-ccb2f432a3a8)
-
-[📚 Documentation](https://dave-b-b.github.io/react-achievements/) | [🎮 Interactive Demo](https://dave-b-b.github.io/react-achievements/?path=/story/introduction--page) | [📦 npm Package](https://www.npmjs.com/package/react-achievements)
+[📚 Documentation](https://dave-b-b.github.io/react-achievements/) | [📦 npm Package](https://www.npmjs.com/package/react-achievements)
 
 [![npm version](https://img.shields.io/npm/v/react-achievements.svg)](https://www.npmjs.com/package/react-achievements) [![License](https://img.shields.io/badge/license-Dual%20(MIT%20%2B%20Commercial)-blue.svg)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
+<p align="center">
+  <a href="https://github.com/dave-b-b/react-achievements/raw/main/assets/Demo.mov">
+    <img
+      src="https://raw.githubusercontent.com/dave-b-b/react-achievements/main/assets/compact.png"
+      alt="React Achievements demo showing a LearnQuest achievements modal"
+      width="900"
+    />
+  </a>
+</p>
+
 ## Installation
 
 ```bash
 npm install react-achievements
 ```
 
-**Requirements:** React 17.0+, Node.js 16+
+**Requirements:** React 16.8+, Node.js 16+
 
----
-
-## Start Here (60 Seconds)
+## Start Here
 
 ```tsx
-import { AchievementProvider, useSimpleAchievements, BadgesButtonWithModal } from 'react-achievements';
+import {
+  AchievementProvider,
+  AchievementsWidget,
+  useSimpleAchievements,
+} from 'react-achievements';
 
 const achievements = {
   score: {
     100: { title: 'Century!', description: 'Score 100 points', icon: '🏆' },
-  }
+  },
 };
 
-function AchievementsUI() {
-  const { track, unlocked } = useSimpleAchievements();
+function Game() {
+  const { track } = useSimpleAchievements();
 
   return (
-    <div>
-      <button onClick={() => track('score', 100)}>Score 100</button>
-      <BadgesButtonWithModal unlockedAchievements={unlocked} />
-    </div>
+    <button onClick={() => track('score', 100)}>
+      Score 100
+    </button>
   );
 }
 
 export default function App() {
   return (
-    <AchievementProvider achievements={achievements} useBuiltInUI={true}>
-      <AchievementsUI />
+    <AchievementProvider achievements={achievements}>
+      <Game />
+      <AchievementsWidget />
     </AchievementProvider>
   );
 }
 ```
 
----
-
-## Usage
+`AchievementsWidget` reads from context, shows the unlocked count, and opens a modal with locked and unlocked achievements. Use `placement="inline"` to put it in a drawer, sidebar, or navigation area. For an exact visual match, pass `renderTrigger` and use your app's own drawer row, nav item, or profile menu button while the widget still controls the modal.
 
-React Achievements supports two tracking patterns:
+```tsx
+<AchievementsWidget
+  placement="inline"
+  renderTrigger={({ buttonProps, unlockedCount, totalCount }) => (
+    <button {...buttonProps} className="drawer-row">
+      Achievements
+      <span>{unlockedCount}/{totalCount}</span>
+    </button>
+  )}
+/>
+```
 
-### Pattern 1: Event-Based Tracking
+## Common Placements
 
-Track achievements using semantic events. Perfect for complex applications or multi-framework projects.
+Use the same context-aware UI in whichever surface already fits your app:
 
 ```tsx
-// achievementEngine.ts
-import { AchievementEngine } from 'react-achievements';
+import { useState } from 'react';
+import {
+  AchievementsList,
+  AchievementsModal,
+  AchievementsWidget,
+} from 'react-achievements';
 
-const achievements = {
-  score: {
-    100: { title: 'Century!', description: 'Score 100 points', icon: '🏆' },
-  }
-};
+// Floating launcher in a corner
+<AchievementsWidget position="bottom-right" />
 
-const eventMapping = {
-  'userScored': (data) => ({ score: data.points }),
-};
+// Inline nav, drawer, sidebar, or profile menu item
+<AchievementsWidget placement="inline" label="Badges" />
 
-export const engine = new AchievementEngine({
-  achievements,
-  eventMapping,
-  storage: 'local'
-});
-```
+// Compact square badge grid for dense achievement catalogs
+<AchievementsWidget density="compact" />
 
-```tsx
-// App.tsx
-import { AchievementProvider } from 'react-achievements';
-import { engine } from './achievementEngine';
+// Optional: blur the page behind the modal
+<AchievementsWidget modalBackdropBlur={2} />
 
-function App() {
-  return (
-    <AchievementProvider engine={engine} useBuiltInUI={true}>
-      <Game />
-    </AchievementProvider>
-  );
-}
-```
+// Existing button or drawer row that opens the built-in modal
+const [open, setOpen] = useState(false);
 
-```tsx
-// Game.tsx
-import { useAchievementEngine } from 'react-achievements';
+<button onClick={() => setOpen(true)}>View achievements</button>
 
-function Game() {
-  const engine = useAchievementEngine();
-  
-  return (
-    <button onClick={() => engine.emit('userScored', { points: 100 })}>
-      Score Points
-    </button>
-  );
-}
+// Optional: hide scrollbar chrome while preserving scroll
+<AchievementsModal
+  isOpen={open}
+  onClose={() => setOpen(false)}
+  hideScrollbar
+  backdropBlur={2}
+/>
+
+// Inline achievements page, panel, drawer, or settings section
+<AchievementsList showLocked />
 ```
 
-➡️ **[Event-Based Tracking Guide](https://dave-b-b.github.io/react-achievements/docs/guides/event-based-tracking)**
+For modal blur props, pass a number for pixels or a CSS length string. Omit the prop or pass `0` when you do not want backdrop blur.
+
+Storybook includes examples for floating buttons, nav buttons, drawer rows, existing controls that open a modal, dashboard cards, profile menus, and inline lists.
 
----
+Provider-level icons and UI options are shared across notifications, widgets, modals, and lists:
 
-### Pattern 2: Direct Track Updates
+```tsx
+<AchievementProvider
+  achievements={achievements}
+  icons={{ login: '🔑', streak: '🔥' }}
+  ui={{
+    theme: 'minimal',
+    NotificationComponent: MyNotification,
+    ModalComponent: MyAchievementsModal,
+    ConfettiComponent: MyConfetti,
+  }}
+>
+  <App />
+</AchievementProvider>
+```
 
-Update metrics directly in your React components. Perfect for simple applications or quick prototypes.
+## Hooks
 
 ```tsx
-// achievements.ts
-const achievements = {
-  score: {
-    100: { title: 'Century!', description: 'Score 100 points', icon: '🏆' },
-  }
-};
+const {
+  track,
+  increment,
+  trackMultiple,
+  unlockedIds,
+  unlockedAchievements,
+  allAchievements,
+  unlockedCount,
+  totalCount,
+} = useSimpleAchievements();
 ```
 
+Deprecated aliases from v3, including `unlocked`, remain available until `4.2`.
+
+## Event-Based Tracking
+
+For larger apps, create an engine and emit semantic events:
+
 ```tsx
-// App.tsx
-import { AchievementProvider } from 'react-achievements';
+import {
+  AchievementEngine,
+  AchievementProvider,
+  AchievementsWidget,
+  useAchievementEngine,
+} from 'react-achievements';
+
+const engine = new AchievementEngine({
+  achievements,
+  eventMapping: {
+    userScored: (data) => ({ score: data.points }),
+  },
+  storage: 'local',
+});
 
-function App() {
+function Game() {
+  const engine = useAchievementEngine();
+  return <button onClick={() => engine.emit('userScored', { points: 100 })}>Score</button>;
+}
+
+export default function App() {
   return (
-    <AchievementProvider achievements={achievements} useBuiltInUI={true}>
+    <AchievementProvider engine={engine}>
       <Game />
+      <AchievementsWidget />
     </AchievementProvider>
   );
 }
 ```
 
+## Headless Usage
+
+Use the DOM-free entry point when building custom UI or preparing a React Native integration:
+
 ```tsx
-// Game.tsx
-import { useSimpleAchievements, BadgesButtonWithModal } from 'react-achievements';
+import {
+  AchievementProvider,
+  useAchievementState,
+  useSimpleAchievements,
+} from 'react-achievements/headless';
 
-function Game() {
-  const { track, unlocked } = useSimpleAchievements();
+function CustomAchievementsPanel() {
+  const { track } = useSimpleAchievements();
+  const { allAchievements, unlockedCount, totalCount } = useAchievementState();
 
   return (
-    <div>
-      <button onClick={() => track('score', 100)}>Score Points</button>
-      <BadgesButtonWithModal unlockedAchievements={unlocked} />
-    </div>
+    <section>
+      <button onClick={() => track('score', 100)}>Score 100</button>
+      <p>{unlockedCount} / {totalCount} unlocked</p>
+
+      {allAchievements.map((achievement) => (
+        <div key={achievement.achievementId}>
+          {achievement.isUnlocked ? 'Unlocked' : 'Locked'}: {achievement.achievementTitle}
+        </div>
+      ))}
+    </section>
+  );
+}
+
+export function App() {
+  return (
+    <AchievementProvider achievements={achievements}>
+      <CustomAchievementsPanel />
+    </AchievementProvider>
   );
 }
 ```
 
-➡️ **[Direct Updates Guide](https://dave-b-b.github.io/react-achievements/docs/guides/direct-updates)**
+React Native UI components are not included in the web package; use `achievements-engine` or the `/headless` React APIs with your own native UI.
 
----
+## Entry Points
 
-## Documentation
+- `react-achievements` - v4 web API with provider, hooks, built-in effects, widget, modal, and list components
+- `react-achievements/web` - explicit web entry point
+- `react-achievements/headless` - provider, hooks, engine, storage, and types without DOM UI
 
-📚 **[Full Documentation](https://dave-b-b.github.io/react-achievements/)** - Complete guides, API reference, and examples
+## Migrating From v3
 
----
+- Built-in UI is now the default; `useBuiltInUI` is a deprecated no-op.
+- `AchievementsWidget` replaces the legacy manual `BadgesButtonWithModal` setup.
+- `useSimpleAchievements()` now returns `unlockedIds`, `unlockedAchievements`, and `allAchievements`.
+- External UI peer dependencies are no longer required.
+- Deprecated v3 component names remain as compatibility wrappers until `4.2`.
 
 ## License
 
-React Achievements is **dual-licensed**:
-
-- **Free for Non-Commercial Use** (MIT License) - Personal projects, education, non-profits, open source
-- **Commercial License Required** - Businesses, SaaS, commercial apps, enterprise
-
-**[Get Commercial License →](https://github.com/sponsors/dave-b-b)** | **[License Details](./LICENSE)** | **[Commercial Terms](./COMMERCIAL-LICENSE.md)**
+React Achievements is dual-licensed:
 
----
+- **Free for Non-Commercial Use** (MIT License)
+- **Commercial License Required** for businesses, SaaS, commercial apps, and enterprise use
 
-**Built with ❤️ by [Dave B](https://github.com/dave-b-b)** | [📚 Documentation](https://dave-b-b.github.io/react-achievements/) | [⭐ Star on GitHub](https://github.com/dave-b-b/react-achievements)
+[Get Commercial License](https://github.com/sponsors/dave-b-b) | [License Details](./LICENSE) | [Commercial Terms](./COMMERCIAL-LICENSE.md)
 
 ## AI Agents
 
-If you're using AI coding agents, see `AGENTS.md` for a concise integration prompt, pitfalls, and the recommended API.
+If you're using AI coding agents, see `AGENTS.md` for the recommended v4 integration prompt.

package/dist/headless.cjs

@@ -0,0 +1,317 @@
+'use strict';
+
+var React = require('react');
+var achievementsEngine = require('achievements-engine');
+
+// Type guard to detect async storage
+function isAsyncStorage(storage) {
+    // Check if methods return Promises
+    const testResult = storage.getMetrics();
+    return testResult && typeof testResult.then === 'function';
+}
+var StorageType;
+(function (StorageType) {
+    StorageType["Local"] = "local";
+    StorageType["Memory"] = "memory";
+    StorageType["IndexedDB"] = "indexeddb";
+    StorageType["RestAPI"] = "restapi"; // Asynchronous REST API storage
+})(StorageType || (StorageType = {}));
+
+const warnedMessages = new Set();
+function warnDeprecation(message) {
+    var _a, _b;
+    const isProduction = typeof globalThis !== 'undefined' &&
+        ((_b = (_a = globalThis.process) === null || _a === void 0 ? void 0 : _a.env) === null || _b === void 0 ? void 0 : _b.NODE_ENV) === 'production';
+    if (isProduction || warnedMessages.has(message)) {
+        return;
+    }
+    warnedMessages.add(message);
+    console.warn(`[react-achievements] ${message}`);
+}
+
+const AchievementContext = React.createContext(undefined);
+const getAllAchievementRecord = (engine) => {
+    return Object.fromEntries(engine.getAllAchievements().map((achievement) => [
+        achievement.achievementId,
+        achievement,
+    ]));
+};
+const AchievementProvider = ({ achievements: achievementsConfig, storage = 'local', children, onError, useBuiltInUI, restApiConfig, engine: externalEngine, eventMapping, icons = {}, }) => {
+    if (useBuiltInUI !== undefined) {
+        warnDeprecation('`useBuiltInUI` is deprecated and is now a no-op because built-in UI is the default. It will be removed in 4.2.');
+    }
+    if (achievementsConfig && externalEngine) {
+        throw new Error('Cannot provide both "achievements" and "engine" props to AchievementProvider.\n\n' +
+            'Choose one pattern:\n' +
+            '1. Direct metric tracking: <AchievementProvider achievements={config}>\n' +
+            '2. Event-based tracking: <AchievementProvider engine={myEngine}>');
+    }
+    const isProviderCreatedEngine = Boolean(achievementsConfig);
+    const [engine] = React.useState(() => {
+        if (externalEngine) {
+            return externalEngine;
+        }
+        if (!achievementsConfig) {
+            throw new Error('AchievementProvider requires either "achievements" or "engine" prop.\n\n' +
+                '1. Direct metric tracking: <AchievementProvider achievements={config}>\n' +
+                '2. Event-based tracking: <AchievementProvider engine={myEngine}>');
+        }
+        return new achievementsEngine.AchievementEngine({
+            achievements: achievementsConfig,
+            storage: storage,
+            restApiConfig,
+            onError: onError,
+            eventMapping,
+        });
+    });
+    const [achievementState, setAchievementState] = React.useState(() => ({
+        unlocked: [...engine.getUnlocked()],
+        all: getAllAchievementRecord(engine),
+    }));
+    const syncAchievementState = React.useCallback(() => {
+        setAchievementState({
+            unlocked: [...engine.getUnlocked()],
+            all: getAllAchievementRecord(engine),
+        });
+    }, [engine]);
+    React.useEffect(() => {
+        return () => {
+            if (!externalEngine) {
+                engine.destroy();
+            }
+        };
+    }, [engine, externalEngine]);
+    React.useEffect(() => {
+        const unsubscribeUnlocked = engine.on('achievement:unlocked', syncAchievementState);
+        const unsubscribeStateChanged = engine.on('state:changed', syncAchievementState);
+        return () => {
+            unsubscribeUnlocked();
+            unsubscribeStateChanged();
+        };
+    }, [engine, syncAchievementState]);
+    const update = (newMetrics) => {
+        engine.update(newMetrics);
+    };
+    const reset = () => {
+        engine.reset();
+        syncAchievementState();
+    };
+    const getState = () => {
+        const metrics = engine.getMetrics();
+        const unlocked = engine.getUnlocked();
+        const metricsInArrayFormat = {};
+        Object.entries(metrics).forEach(([key, value]) => {
+            metricsInArrayFormat[key] = Array.isArray(value) ? value : [value];
+        });
+        return {
+            metrics: metricsInArrayFormat,
+            unlocked: [...unlocked],
+        };
+    };
+    const exportData = () => {
+        return engine.export();
+    };
+    const importData = (jsonString, options) => {
+        const result = engine.import(jsonString, options);
+        syncAchievementState();
+        return result;
+    };
+    const getAllAchievements = () => {
+        return engine.getAllAchievements();
+    };
+    return (React.createElement(AchievementContext.Provider, { value: {
+            update,
+            achievements: achievementState,
+            reset,
+            getState,
+            exportData,
+            importData,
+            getAllAchievements,
+            engine,
+            icons,
+            _isLegacyPattern: isProviderCreatedEngine,
+        } }, children));
+};
+
+const useAchievements = () => {
+    const context = React.useContext(AchievementContext);
+    if (!context) {
+        throw new Error('useAchievements must be used within an AchievementProvider');
+    }
+    return context;
+};
+
+const useAchievementState = () => {
+    const { achievements, getAllAchievements, getState } = useAchievements();
+    const allAchievements = getAllAchievements();
+    const unlockedIds = achievements.unlocked;
+    const unlockedAchievementSet = new Set(unlockedIds);
+    const unlockedAchievements = allAchievements.filter((achievement) => unlockedAchievementSet.has(achievement.achievementId));
+    return {
+        unlockedIds,
+        unlockedAchievements,
+        allAchievements,
+        unlockedCount: unlockedIds.length,
+        totalCount: allAchievements.length,
+        metrics: getState().metrics,
+    };
+};
+
+/**
+ * A simplified hook for achievement tracking.
+ * Provides the v4 happy path for direct metric updates plus explicit state names.
+ */
+const useSimpleAchievements = () => {
+    const { update, reset, getState, exportData, importData } = useAchievements();
+    const achievementState = useAchievementState();
+    const track = (metric, value) => update({ [metric]: value });
+    const increment = (metric, amount = 1) => {
+        const currentState = getState();
+        const currentMetricArray = currentState.metrics[metric] || [0];
+        const currentValue = Array.isArray(currentMetricArray)
+            ? currentMetricArray[0]
+            : currentMetricArray;
+        const newValue = (typeof currentValue === 'number' ? currentValue : 0) + amount;
+        update({ [metric]: newValue });
+    };
+    const trackMultiple = (metrics) => update(metrics);
+    return {
+        track,
+        increment,
+        trackMultiple,
+        unlockedIds: achievementState.unlockedIds,
+        unlockedAchievements: achievementState.unlockedAchievements,
+        allAchievements: achievementState.allAchievements,
+        unlockedCount: achievementState.unlockedCount,
+        totalCount: achievementState.totalCount,
+        metrics: achievementState.metrics,
+        reset,
+        getState,
+        exportData,
+        importData,
+        getAllAchievements: () => achievementState.allAchievements,
+        /**
+         * @deprecated Use `unlockedIds` instead. This alias will be removed in 4.2.
+         */
+        unlocked: achievementState.unlockedIds,
+        /**
+         * @deprecated Use `allAchievements` instead. This alias will be removed in 4.2.
+         */
+        all: achievementState.allAchievements,
+    };
+};
+
+/**
+ * Access the active AchievementEngine instance.
+ *
+ * In v4 this works with both provider-created engines (`achievements` prop) and
+ * injected engines (`engine` prop).
+ */
+const useAchievementEngine = () => {
+    const context = React.useContext(AchievementContext);
+    if (!context) {
+        throw new Error('useAchievementEngine must be used within an AchievementProvider.\n\n' +
+            'Wrap your component tree:\n' +
+            '<AchievementProvider achievements={achievements}>\n' +
+            '  <YourComponent />\n' +
+            '</AchievementProvider>');
+    }
+    return context.engine;
+};
+
+Object.defineProperty(exports, 'AchievementBuilder', {
+    enumerable: true,
+    get: function () { return achievementsEngine.AchievementBuilder; }
+});
+Object.defineProperty(exports, 'AchievementEngine', {
+    enumerable: true,
+    get: function () { return achievementsEngine.AchievementEngine; }
+});
+Object.defineProperty(exports, 'AchievementError', {
+    enumerable: true,
+    get: function () { return achievementsEngine.AchievementError; }
+});
+Object.defineProperty(exports, 'AsyncStorageAdapter', {
+    enumerable: true,
+    get: function () { return achievementsEngine.AsyncStorageAdapter; }
+});
+Object.defineProperty(exports, 'ConfigurationError', {
+    enumerable: true,
+    get: function () { return achievementsEngine.ConfigurationError; }
+});
+Object.defineProperty(exports, 'ImportValidationError', {
+    enumerable: true,
+    get: function () { return achievementsEngine.ImportValidationError; }
+});
+Object.defineProperty(exports, 'IndexedDBStorage', {
+    enumerable: true,
+    get: function () { return achievementsEngine.IndexedDBStorage; }
+});
+Object.defineProperty(exports, 'LocalStorage', {
+    enumerable: true,
+    get: function () { return achievementsEngine.LocalStorage; }
+});
+Object.defineProperty(exports, 'MemoryStorage', {
+    enumerable: true,
+    get: function () { return achievementsEngine.MemoryStorage; }
+});
+Object.defineProperty(exports, 'OfflineQueueStorage', {
+    enumerable: true,
+    get: function () { return achievementsEngine.OfflineQueueStorage; }
+});
+Object.defineProperty(exports, 'RestApiStorage', {
+    enumerable: true,
+    get: function () { return achievementsEngine.RestApiStorage; }
+});
+Object.defineProperty(exports, 'StorageError', {
+    enumerable: true,
+    get: function () { return achievementsEngine.StorageError; }
+});
+Object.defineProperty(exports, 'StorageQuotaError', {
+    enumerable: true,
+    get: function () { return achievementsEngine.StorageQuotaError; }
+});
+Object.defineProperty(exports, 'StorageType', {
+    enumerable: true,
+    get: function () { return achievementsEngine.StorageType; }
+});
+Object.defineProperty(exports, 'SyncError', {
+    enumerable: true,
+    get: function () { return achievementsEngine.SyncError; }
+});
+Object.defineProperty(exports, 'createConfigHash', {
+    enumerable: true,
+    get: function () { return achievementsEngine.createConfigHash; }
+});
+Object.defineProperty(exports, 'exportAchievementData', {
+    enumerable: true,
+    get: function () { return achievementsEngine.exportAchievementData; }
+});
+Object.defineProperty(exports, 'importAchievementData', {
+    enumerable: true,
+    get: function () { return achievementsEngine.importAchievementData; }
+});
+Object.defineProperty(exports, 'isAchievementError', {
+    enumerable: true,
+    get: function () { return achievementsEngine.isAchievementError; }
+});
+Object.defineProperty(exports, 'isRecoverableError', {
+    enumerable: true,
+    get: function () { return achievementsEngine.isRecoverableError; }
+});
+Object.defineProperty(exports, 'isSimpleConfig', {
+    enumerable: true,
+    get: function () { return achievementsEngine.isSimpleConfig; }
+});
+Object.defineProperty(exports, 'normalizeAchievements', {
+    enumerable: true,
+    get: function () { return achievementsEngine.normalizeAchievements; }
+});
+exports.AchievementContext = AchievementContext;
+exports.AchievementProvider = AchievementProvider;
+exports.isAsyncStorage = isAsyncStorage;
+exports.useAchievementEngine = useAchievementEngine;
+exports.useAchievementState = useAchievementState;
+exports.useAchievements = useAchievements;
+exports.useSimpleAchievements = useSimpleAchievements;
+//# sourceMappingURL=headless.cjs.map