@dismissible/react-client 0.3.2-canary.2.38782c4 → 0.3.2-canary.3.c1b8c41

package/README.md

@@ -1,10 +1,10 @@
 # @dismissible/react-client
 
-A React component library for creating dismissible UI elements with persistent state management. 
+A React component library for creating dismissible UI elements with persistent state management.
 
-Use this in combination with [dismissible.io](https://dismissible.io). Get your free account now!
+**Free and open source** - use with the [Dismissible API Server](https://github.com/DismissibleIo/dismissible-api) that you can self-host with Docker or integrate into your NestJS application.
 
-🌐 **[dismissible.io](https://dismissible.io)** | 💰 **[View Pricing](https://dismissible.io/pricing)** | 📖 **[Documentation](https://docs.dismissible.io)**
+🌐 **[dismissible.io](https://dismissible.io)** | 📖 **[Documentation](https://dismissible.io/docs)** | 🐙 **[API Server](https://github.com/DismissibleIo/dismissible-api)**
 
 [![npm version](https://badge.fury.io/js/@dismissible%2Freact-client.svg)](https://badge.fury.io/js/@dismissible%2Freact-client)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -13,12 +13,14 @@ Use this in combination with [dismissible.io](https://dismissible.io). Get your
 
 - 🎯 **Easy to use** - Simple component API for dismissible content
 - 💾 **Persistent state** - Dismissal state is saved and restored across sessions
-- 🔐 **JWT Authentication** - Built-in support for JWT-based user authentication (Enterprise only)
+- 🔄 **Restore support** - Restore previously dismissed items programmatically
+- 🔐 **JWT Authentication** - Built-in support for secure JWT-based authentication
 - 🎨 **Customizable** - Custom loading, error, and dismiss button components
 - ♿ **Accessible** - Built with accessibility best practices
 - 🪝 **Hook-based** - Includes `useDismissibleItem` hook for custom implementations
 - 📦 **Lightweight** - Minimal bundle size with tree-shaking support
 - 🔧 **TypeScript** - Full TypeScript support with complete type definitions
+- 🐳 **Self-hosted** - Works with your own Dismissible API server
 
 ## Installation
 
@@ -36,13 +38,69 @@ npm install react react-dom
 
 ## Quick Start
 
+### 1. Set up the Dismissible API Server
+
+First, you need a Dismissible API server running. The easiest way is with Docker:
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+services:
+  api:
+    image: dismissibleio/dismissible-api:latest
+    ports:
+      - '3001:3001'
+    environment:
+      DISMISSIBLE_PORT: 3001
+      DISMISSIBLE_POSTGRES_STORAGE_CONNECTION_STRING: postgresql://postgres:postgres@db:5432/dismissible
+    depends_on:
+      - db
+
+  db:
+    image: postgres:15
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: dismissible
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  postgres_data:
+```
+
+```bash
+docker-compose up -d
+```
+
+See the [API Server documentation](https://github.com/DismissibleIo/dismissible-api) for more deployment options including NestJS integration.
+
+### 2. Configure the Provider
+
+Wrap your app with `DismissibleProvider`. The `userId` prop is **required** to track dismissals per user:
+
 ```tsx
-import React from 'react';
-import { Dismissible } from '@dismissible/react-client';
+import { DismissibleProvider } from '@dismissible/react-client';
 
 function App() {
+  const userId = getCurrentUserId(); // Get from your auth system
+  
   return (
-    <Dismissible id="welcome-banner-123-413-31-1">
+    <DismissibleProvider userId={userId} baseUrl="http://localhost:3001">
+      <YourApp />
+    </DismissibleProvider>
+  );
+}
+```
+
+### 3. Use Dismissible Components
+
+```tsx
+import { Dismissible } from '@dismissible/react-client';
+
+function WelcomeBanner() {
+  return (
+    <Dismissible id="welcome-banner">
       <div className="banner">
         <h2>Welcome to our app!</h2>
         <p>This banner can be dismissed and won't show again.</p>
@@ -56,16 +114,15 @@ function App() {
 
 ### `<DismissibleProvider>` Component
 
-Context provider for JWT authentication and configuration. Wrap your app or components that need JWT authentication.
-
-> **Note:** JWT authentication is only available for **Enterprise customers**. For standard usage, you can use the `<Dismissible>` component directly without a provider. [View pricing →](https://dismissible.io/pricing)
+Context provider that configures authentication and API settings. **Required** - all `<Dismissible>` components must be wrapped in a provider.
 
 #### Props
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
-| `jwt` | `string \| (() => string) \| (() => Promise<string>)` | ❌ | JWT token for user-specific dismissals (**Enterprise only**) |
-| `baseUrl` | `string` | ❌ | Custom API base URL override |
+| `userId` | `string` | ✅ | User ID for tracking dismissals per user |
+| `jwt` | `string \| (() => string) \| (() => Promise<string>)` | ❌ | JWT token for secure authentication |
+| `baseUrl` | `string` | ❌ | API base URL (defaults to your self-hosted server) |
 | `children` | `ReactNode` | ✅ | Components that will use the dismissible functionality |
 
 #### Example
@@ -73,37 +130,53 @@ Context provider for JWT authentication and configuration. Wrap your app or comp
 ```tsx
 import { DismissibleProvider } from '@dismissible/react-client';
 
-// With static JWT
+// Basic setup with userId
 function App() {
   return (
-    <DismissibleProvider jwt="eyJhbGciOiJIUzI1NiIs...">
+    <DismissibleProvider userId="user-123" baseUrl="http://localhost:3001">
       <YourApp />
     </DismissibleProvider>
   );
 }
 
-// With dynamic JWT function
-function AppWithDynamicAuth() {
+// With static JWT
+function AppWithJWT() {
   return (
-    <DismissibleProvider jwt={() => getAccessToken()}>
+    <DismissibleProvider 
+      userId="user-123" 
+      jwt="eyJhbGciOiJIUzI1NiIs..."
+      baseUrl="https://api.yourapp.com"
+    >
       <YourApp />
     </DismissibleProvider>
   );
 }
 
-// With async JWT function
-function AppWithAsyncAuth() {
+// With dynamic JWT function
+function AppWithDynamicAuth() {
+  const { user, getAccessToken } = useAuth();
+  
   return (
-    <DismissibleProvider jwt={async () => await fetchAccessToken()}>
+    <DismissibleProvider 
+      userId={user.id} 
+      jwt={() => getAccessToken()}
+      baseUrl="https://api.yourapp.com"
+    >
       <YourApp />
     </DismissibleProvider>
   );
 }
 
-// Without JWT (anonymous/backwards compatible)
-function AppWithoutAuth() {
+// With async JWT function
+function AppWithAsyncAuth() {
+  const { user, refreshAndGetToken } = useAuth();
+  
   return (
-    <DismissibleProvider>
+    <DismissibleProvider 
+      userId={user.id} 
+      jwt={async () => await refreshAndGetToken()}
+      baseUrl="https://api.yourapp.com"
+    >
       <YourApp />
     </DismissibleProvider>
   );
@@ -114,6 +187,8 @@ function AppWithoutAuth() {
 
 The main component for creating dismissible content.
 
+> **Note:** The `<Dismissible>` component renders `null` when an item is dismissed. For restore functionality, use the `useDismissibleItem` hook directly in custom implementations.
+
 #### Props
 
 | Prop | Type | Required | Description |
@@ -125,6 +200,9 @@ The main component for creating dismissible content.
 | `ErrorComponent` | `ComponentType<{id: string, error: Error}>` | ❌ | Custom error component |
 | `DismissButtonComponent` | `ComponentType<{id: string, onDismiss: () => Promise<void>, ariaLabel: string}>` | ❌ | Custom dismiss button |
 | `ignoreErrors` | `boolean` | ❌ | Ignore errors and display component anyway (default: false) |
+| `enableCache` | `boolean` | ❌ | Enable localStorage caching (default: true) |
+| `cachePrefix` | `string` | ❌ | Cache key prefix (default: 'dismissible') |
+| `cacheExpiration` | `number` | ❌ | Cache expiration time in milliseconds |
 
 #### Example
 
@@ -132,7 +210,6 @@ The main component for creating dismissible content.
 <Dismissible
   id="promo-banner"
   onDismiss={() => console.log('Banner dismissed')}
-  onRestore={() => console.log('Banner restored')}
 >
   <div className="promo">
     <h3>Special Offer!</h3>
@@ -150,6 +227,7 @@ For custom implementations and advanced use cases.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `id` | `string` | ✅ | Unique identifier for the dismissible item |
+| `options` | `object` | ❌ | Cache configuration options |
 
 #### Returns
 
@@ -157,8 +235,10 @@ For custom implementations and advanced use cases.
 |----------|------|-------------|
 | `dismissedOn` | `string \| null` | ISO date string when item was dismissed, or null |
 | `dismiss` | `() => Promise<void>` | Function to dismiss the item |
+| `restore` | `() => Promise<void>` | Function to restore a dismissed item |
 | `isLoading` | `boolean` | Loading state indicator |
 | `error` | `Error \| null` | Error state, if any |
+| `item` | `IDismissibleItem \| undefined` | The full dismissible item object |
 
 #### Example
 
@@ -166,11 +246,7 @@ For custom implementations and advanced use cases.
 import { useDismissibleItem } from '@dismissible/react-client';
 
 function CustomDismissible({ id, children }) {
-  const { dismissedOn, dismiss, isLoading, error } = useDismissibleItem(id);
-
-  if (dismissedOn) {
-    return null; // Item is dismissed
-  }
+  const { dismissedOn, dismiss, restore, isLoading, error } = useDismissibleItem(id);
 
   if (isLoading) {
     return <div>Loading...</div>;
@@ -180,6 +256,15 @@ function CustomDismissible({ id, children }) {
     return <div>Error: {error.message}</div>;
   }
 
+  if (dismissedOn) {
+    return (
+      <div>
+        <p>This item was dismissed.</p>
+        <button onClick={restore}>Restore</button>
+      </div>
+    );
+  }
+
   return (
     <div>
       {children}
@@ -193,21 +278,16 @@ function CustomDismissible({ id, children }) {
 
 ## Usage Examples
 
-### JWT Authentication Setup (Enterprise Only)
-
-> **Enterprise Feature:** JWT authentication allows user-specific dismissible state management. This feature requires an Enterprise subscription. [Learn more about Enterprise features →](https://dismissible.io/pricing)
-
-For enterprise accounts that require user-specific dismissible state, wrap your app with the `DismissibleProvider`:
+### Basic Dismissible Banner
 
 ```tsx
 import { DismissibleProvider, Dismissible } from '@dismissible/react-client';
 
 function App() {
-  // Example with static JWT token
-  const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
+  const userId = getCurrentUserId();
   
   return (
-    <DismissibleProvider jwt={jwt}>
+    <DismissibleProvider userId={userId} baseUrl="http://localhost:3001">
       <Dashboard />
     </DismissibleProvider>
   );
@@ -215,61 +295,48 @@ function App() {
 
 function Dashboard() {
   return (
-    <div>
-      {/* These dismissible items will be user-specific */}
-      <Dismissible id="user-welcome-banner">
-        <div className="alert alert-info">
-          <h4>Welcome back!</h4>
-          <p>You have 3 new notifications.</p>
-        </div>
-      </Dismissible>
-    </div>
+    <Dismissible id="welcome-banner">
+      <div className="alert alert-info">
+        <h4>Welcome!</h4>
+        <p>Thanks for joining our platform. Here are some quick tips to get started.</p>
+      </div>
+    </Dismissible>
   );
 }
 ```
 
-### Dynamic JWT with Authentication Provider
+### JWT Authentication Setup
+
+For secure environments, configure JWT authentication:
 
 ```tsx
-import { DismissibleProvider } from '@dismissible/react-client';
-import { useAuth } from './auth'; // Your auth context
+import { DismissibleProvider, Dismissible } from '@dismissible/react-client';
 
-// Synchronous JWT function
 function App() {
-  const { getAccessToken } = useAuth();
+  const { user, getAccessToken } = useAuth();
   
   return (
-    <DismissibleProvider jwt={() => getAccessToken()}>
-      <YourApp />
-    </DismissibleProvider>
-  );
-}
-
-// Asynchronous JWT function
-function AppWithAsyncAuth() {
-  const { refreshAndGetToken } = useAuth();
-  
-  return (
-    <DismissibleProvider jwt={async () => await refreshAndGetToken()}>
-      <YourApp />
+    <DismissibleProvider 
+      userId={user.id}
+      jwt={() => getAccessToken()}
+      baseUrl="https://api.yourapp.com"
+    >
+      <Dashboard />
     </DismissibleProvider>
   );
 }
-```
-
-### Basic Dismissible Banner
-
-```tsx
-import { Dismissible } from '@dismissible/react-client';
 
-function WelcomeBanner() {
+function Dashboard() {
   return (
-    <Dismissible id="welcome-banner-234-432-432-1">
-      <div className="alert alert-info">
-        <h4>Welcome!</h4>
-        <p>Thanks for joining our platform. Here are some quick tips to get started.</p>
-      </div>
-    </Dismissible>
+    <div>
+      {/* Dismissible state is tracked per user */}
+      <Dismissible id="user-welcome-banner">
+        <div className="alert alert-info">
+          <h4>Welcome back!</h4>
+          <p>You have 3 new notifications.</p>
+        </div>
+      </Dismissible>
+    </div>
   );
 }
 ```
@@ -349,19 +416,19 @@ import { Dismissible } from '@dismissible/react-client';
 function Dashboard() {
   return (
     <div>
-      <Dismissible id="feature-announcement-234-432-432-1">
+      <Dismissible id="feature-announcement">
         <div className="alert alert-success">
           🎉 New feature: Dark mode is now available!
         </div>
       </Dismissible>
 
-      <Dismissible id="maintenance-notice-234-432-432-1">
+      <Dismissible id="maintenance-notice">
         <div className="alert alert-warning">
           ⚠️ Scheduled maintenance: Sunday 2AM-4AM EST
         </div>
       </Dismissible>
 
-      <Dismissible id="survey-request-234-432-432-1">
+      <Dismissible id="survey-request">
         <div className="alert alert-info">
           📝 Help us improve! Take our 2-minute survey.
         </div>
@@ -371,35 +438,6 @@ function Dashboard() {
 }
 ```
 
-### User-Specific vs Anonymous Dismissible Items
-
-The behavior changes based on whether JWT authentication is configured:
-
-> **Enterprise vs Standard:** JWT authentication for user-specific dismissals is an Enterprise feature. Standard accounts use anonymous (account-level) dismissals. [Compare plans →](https://dismissible.io/pricing)
-
-```tsx
-import { DismissibleProvider, Dismissible } from '@dismissible/react-client';
-
-// With JWT - dismissible state is user-specific
-function AuthenticatedApp() {
-  return (
-    <DismissibleProvider jwt={() => getAccessToken()}>
-      <div>
-        {/* Each user will see this banner independently */}
-        <Dismissible id="feature-announcement">
-          <div>New feature available!</div>
-        </Dismissible>
-        
-        {/* User A dismissing this won't affect User B */}
-        <Dismissible id="survey-request">
-          <div>Please take our survey!</div>
-        </Dismissible>
-      </div>
-    </DismissibleProvider>
-  );
-}
-```
-
 ### Error Handling with ignoreErrors
 
 ```tsx
@@ -421,57 +459,68 @@ function RobustBanner() {
 }
 ```
 
-### Async JWT Authentication Examples
+### Integration with Auth Providers
 
 ```tsx
 import { DismissibleProvider } from '@dismissible/react-client';
 
-// With token refresh logic
-function AppWithTokenRefresh() {
+// With Firebase Auth
+function AppWithFirebase() {
+  const user = firebase.auth().currentUser;
+  
   return (
     <DismissibleProvider 
+      userId={user.uid}
       jwt={async () => {
-        try {
-          const token = await fetch('/api/auth/refresh', {
-            method: 'POST',
-            credentials: 'include'
-          });
-          const { accessToken } = await token.json();
-          return accessToken;
-        } catch (error) {
-          console.error('Failed to refresh token:', error);
-          throw error;
+        if (user) {
+          return await user.getIdToken();
         }
+        throw new Error('User not authenticated');
       }}
+      baseUrl="https://api.yourapp.com"
     >
       <YourApp />
     </DismissibleProvider>
   );
 }
 
-// With Firebase Auth
-function AppWithFirebase() {
+// With Auth0
+function AppWithAuth0() {
+  const { user, getAccessTokenSilently } = useAuth0();
+  
   return (
     <DismissibleProvider 
-      jwt={async () => {
-        const user = firebase.auth().currentUser;
-        if (user) {
-          return await user.getIdToken();
-        }
-        throw new Error('User not authenticated');
-      }}
+      userId={user.sub}
+      jwt={async () => await getAccessTokenSilently()}
+      baseUrl="https://api.yourapp.com"
     >
       <YourApp />
     </DismissibleProvider>
   );
 }
 
-// With Auth0
-function AppWithAuth0() {
-  const { getAccessTokenSilently } = useAuth0();
+// With token refresh logic
+function AppWithTokenRefresh() {
+  const { user } = useAuth();
   
   return (
-    <DismissibleProvider jwt={async () => await getAccessTokenSilently()}>
+    <DismissibleProvider 
+      userId={user.id}
+      jwt={async () => {
+        try {
+          const response = await fetch('/api/auth/refresh', {
+            method: 'POST',
+            credentials: 'include'
+          });
+          const { accessToken } = await response.json();
+          return accessToken;
+        } catch (error) {
+          console.error('Failed to refresh token:', error);
+          throw error;
+        }
+      }}
+      baseUrl="https://api.yourapp.com"
+    >
       <YourApp />
     </DismissibleProvider>
   );
@@ -481,7 +530,7 @@ function AppWithAuth0() {
 ### Using the Hook for Complex Logic
 
 ```tsx
-import { useDismissibleItem, DismissibleProvider } from '@dismissible/react-client';
+import { useDismissibleItem } from '@dismissible/react-client';
 import { useState, useEffect } from 'react';
 
 function SmartNotification({ id, message, type = 'info' }) {
@@ -517,17 +566,82 @@ function SmartNotification({ id, message, type = 'info' }) {
     </div>
   );
 }
+```
+
+### Restoring Dismissed Items
+
+Use the `restore` function to bring back previously dismissed content:
+
+```tsx
+import { useDismissibleItem } from '@dismissible/react-client';
+
+function RestorableBanner({ id }) {
+  const { dismissedOn, dismiss, restore, isLoading } = useDismissibleItem(id);
+
+  if (dismissedOn) {
+    return (
+      <div className="dismissed-placeholder">
+        <p>Banner was dismissed on {new Date(dismissedOn).toLocaleDateString()}</p>
+        <button onClick={restore} disabled={isLoading}>
+          {isLoading ? 'Restoring...' : 'Show Banner Again'}
+        </button>
+      </div>
+    );
+  }
 
-// Usage with async authentication
-function App() {
   return (
-    <DismissibleProvider jwt={async () => await getUserToken()}>
-      <SmartNotification 
-        id="user-specific-notification" 
-        message="Welcome back!" 
-        type="info" 
-      />
-    </DismissibleProvider>
+    <div className="banner">
+      <h3>Welcome!</h3>
+      <p>This is a restorable banner.</p>
+      <button onClick={dismiss} disabled={isLoading}>
+        Dismiss
+      </button>
+    </div>
+  );
+}
+```
+
+### Admin Panel with Restore Capability
+
+```tsx
+import { useDismissibleItem } from '@dismissible/react-client';
+
+function AdminNotificationManager({ notificationId }) {
+  const { dismissedOn, dismiss, restore, item, isLoading, error } = 
+    useDismissibleItem(notificationId);
+
+  if (error) {
+    return <div className="error">Error: {error.message}</div>;
+  }
+
+  return (
+    <div className="admin-panel">
+      <h4>Notification: {notificationId}</h4>
+      <p>Status: {dismissedOn ? 'Dismissed' : 'Active'}</p>
+      {dismissedOn && (
+        <p>Dismissed at: {new Date(dismissedOn).toLocaleString()}</p>
+      )}
+      
+      <div className="actions">
+        {dismissedOn ? (
+          <button 
+            onClick={restore} 
+            disabled={isLoading}
+            className="btn-restore"
+          >
+            Restore
+          </button>
+        ) : (
+          <button 
+            onClick={dismiss} 
+            disabled={isLoading}
+            className="btn-dismiss"
+          >
+            Dismiss
+          </button>
+        )}
+      </div>
+    </div>
   );
 }
 ```
@@ -564,28 +678,60 @@ import type {
   DismissibleProps,
   DismissibleProviderProps,
   JwtToken,
-  IDismissibleItem 
 } from '@dismissible/react-client';
 
-// Dismissible component with custom props
-const MyComponent: React.FC<DismissibleProps> = (props) => {
-  // Your component implementation
-};
-
-// Provider with JWT authentication
-const AuthProvider: React.FC<DismissibleProviderProps> = ({ children, jwt }) => {
+// Custom provider wrapper
+const AuthenticatedDismissibleProvider: React.FC<{
+  children: React.ReactNode;
+}> = ({ children }) => {
+  const { user, getToken } = useAuth();
+  
   return (
-    <DismissibleProvider jwt={jwt}>
+    <DismissibleProvider 
+      userId={user.id} 
+      jwt={getToken}
+      baseUrl={process.env.DISMISSIBLE_API_URL}
+    >
       {children}
     </DismissibleProvider>
   );
 };
 ```
 
+## Self-Hosting
+
+Dismissible is designed to be self-hosted. You have full control over your data.
+
+### Option 1: Docker (Recommended)
+
+The fastest way to get started:
+
+```bash
+docker run -p 3001:3001 dismissibleio/dismissible-api:latest
+```
+
+See the [Docker documentation](https://dismissible.io/docs/docker) for production configuration.
+
+### Option 2: NestJS Module
+
+Integrate directly into your existing NestJS application:
+
+```bash
+npm install @dismissible/nestjs-api
+```
+
+See the [NestJS documentation](https://dismissible.io/docs/nestjs) for setup instructions.
+
 ## Support
 
-- 📖 [Documentation](https://docs.dismissible.io)
+- 📖 [Documentation](https://dismissible.io/docs)
+- 🐙 [GitHub - React Client](https://github.com/DismissibleIo/dismissible-react-client)
+- 🐙 [GitHub - API Server](https://github.com/DismissibleIo/dismissible-api)
+
+## License
+
+MIT © [Dismissible](https://dismissible.io)
 
 ## Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md) for a detailed list of changes.
+See [CHANGELOG.md](./CHANGELOG.md) for a detailed list of changes.