@dismissible/react-client 0.1.0 → 0.3.0

package/README.md

@@ -9,6 +9,7 @@ A React component library for creating dismissible UI elements with persistent s
 
 - 🎯 **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
 - 🎨 **Customizable** - Custom loading, error, and dismiss button components
 - ♿ **Accessible** - Built with accessibility best practices
 - 🪝 **Hook-based** - Includes `useDismissibleItem` hook for custom implementations
@@ -49,6 +50,51 @@ function App() {
 
 ## API Reference
 
+### `<DismissibleProvider>` Component
+
+Context provider for JWT authentication and configuration. Wrap your app or components that need JWT authentication.
+
+#### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `jwt` | `string \| (() => string)` | ❌ | JWT token (static string or function) |
+| `baseUrl` | `string` | ❌ | Custom API base URL override |
+| `children` | `ReactNode` | ✅ | Components that will use the dismissible functionality |
+
+#### Example
+
+```tsx
+import { DismissibleProvider } from '@dismissible/react-client';
+
+// With static JWT
+function App() {
+  return (
+    <DismissibleProvider jwt="eyJhbGciOiJIUzI1NiIs...">
+      <YourApp />
+    </DismissibleProvider>
+  );
+}
+
+// With dynamic JWT function
+function AppWithDynamicAuth() {
+  return (
+    <DismissibleProvider jwt={() => getAccessToken()}>
+      <YourApp />
+    </DismissibleProvider>
+  );
+}
+
+// Without JWT (anonymous/backwards compatible)
+function AppWithoutAuth() {
+  return (
+    <DismissibleProvider>
+      <YourApp />
+    </DismissibleProvider>
+  );
+}
+```
+
 ### `<Dismissible>` Component
 
 The main component for creating dismissible content.
@@ -131,6 +177,56 @@ function CustomDismissible({ id, children }) {
 
 ## Usage Examples
 
+### JWT Authentication Setup
+
+For enterprise accounts that require user-specific dismissible state, wrap your app with the `DismissibleProvider`:
+
+```tsx
+import { DismissibleProvider, Dismissible } from '@dismissible/react-client';
+
+function App() {
+  // Example with static JWT token
+  const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
+  
+  return (
+    <DismissibleProvider jwt={jwt}>
+      <Dashboard />
+    </DismissibleProvider>
+  );
+}
+
+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>
+  );
+}
+```
+
+### Dynamic JWT with Authentication Provider
+
+```tsx
+import { DismissibleProvider } from '@dismissible/react-client';
+import { useAuth } from './auth'; // Your auth context
+
+function App() {
+  const { getAccessToken } = useAuth();
+  
+  return (
+    <DismissibleProvider jwt={() => getAccessToken()}>
+      <YourApp />
+    </DismissibleProvider>
+  );
+}
+```
+
 ### Basic Dismissible Banner
 
 ```tsx
@@ -271,10 +367,49 @@ function ConditionalBanner({ user }) {
 }
 ```
 
+### User-Specific vs Anonymous Dismissible Items
+
+The behavior changes based on whether JWT authentication is configured:
+
+```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>
+  );
+}
+
+// Without JWT - dismissible state is account-level (anonymous)
+function AnonymousApp() {
+  return (
+    <div>
+      {/* These will be dismissed for all users of this account */}
+      <Dismissible id="general-announcement">
+        <div>Site maintenance scheduled</div>
+      </Dismissible>
+    </div>
+  );
+}
+```
+
 ### Using the Hook for Complex Logic
 
 ```tsx
-import { useDismissibleItem } from '@dismissible/react-client';
+import { useDismissibleItem, DismissibleProvider } from '@dismissible/react-client';
 import { useState, useEffect } from 'react';
 
 function SmartNotification({ id, message, type = 'info' }) {
@@ -310,6 +445,19 @@ function SmartNotification({ id, message, type = 'info' }) {
     </div>
   );
 }
+
+// Usage with authentication
+function App() {
+  return (
+    <DismissibleProvider jwt={() => getUserToken()}>
+      <SmartNotification 
+        id="user-specific-notification" 
+        message="Welcome back!" 
+        type="info" 
+      />
+    </DismissibleProvider>
+  );
+}
 ```
 
 ## Styling
@@ -342,12 +490,24 @@ The library is written in TypeScript and exports all type definitions:
 ```tsx
 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 }) => {
+  return (
+    <DismissibleProvider jwt={jwt}>
+      {children}
+    </DismissibleProvider>
+  );
+};
 ```
 
 ## Development

package/dist/components/Dismissible.d.ts

@@ -30,6 +30,8 @@ export interface DismissibleProps {
     cachePrefix?: string;
     /** Cache expiration time in milliseconds (default: never expires) */
     cacheExpiration?: number;
+    /** Ignore errors and display the component anyway (default: false) */
+    ignoreErrors?: boolean;
 }
 /**
  * A wrapper component that can be dismissed and hidden by users
@@ -44,6 +46,7 @@ export interface DismissibleProps {
  * @param enableCache - Enable localStorage caching
  * @param cachePrefix - Cache key prefix
  * @param cacheExpiration - Cache expiration time in milliseconds
+ * @param ignoreErrors - Ignore errors and display the component anyway
  * @returns JSX element or null if dismissed
  */
 export declare const Dismissible: React.FC<DismissibleProps>;

package/dist/contexts/DismissibleContext.d.ts

@@ -0,0 +1,10 @@
+import { DismissibleContextValue } from '../types/dismissible.types';
+/**
+ * React context for sharing dismissible authentication state
+ */
+export declare const DismissibleContext: import('react').Context<DismissibleContextValue | null>;
+/**
+ * Hook to consume the DismissibleContext
+ * @returns The context value or null if not within a provider
+ */
+export declare const useDismissibleContext: () => DismissibleContextValue | null;

package/dist/contexts/DismissibleProvider.d.ts

@@ -0,0 +1,30 @@
+import { default as React } from 'react';
+import { DismissibleProviderProps } from '../types/dismissible.types';
+/**
+ * Provider component for managing dismissible authentication state
+ *
+ * @example
+ * ```tsx
+ * // With static JWT
+ * <DismissibleProvider jwt="eyJhbGciOiJ..." baseUrl="https://api.dismissible.io">
+ *   <App />
+ * </DismissibleProvider>
+ *
+ * // With synchronous JWT function
+ * <DismissibleProvider
+ *   jwt={() => getAccessToken()}
+ *   baseUrl="https://api.dismissible.io"
+ * >
+ *   <App />
+ * </DismissibleProvider>
+ *
+ * // With asynchronous JWT function
+ * <DismissibleProvider
+ *   jwt={async () => await fetchAccessToken()}
+ *   baseUrl="https://api.dismissible.io"
+ * >
+ *   <App />
+ * </DismissibleProvider>
+ * ```
+ */
+export declare const DismissibleProvider: React.FC<DismissibleProviderProps>;