shared-features 0.0.1 → 0.0.3

package/README.md

@@ -5,6 +5,9 @@ Centralized common features for Zaions projects. Manage ads, contacts, feature r
 ## Features
 
 - **Advertising Campaigns** - Cross-promote Zaions products across all projects
+  - 5 Ad Components (AdPanel, AdSlider, AdModal, AdUpdateModal, AdBanner)
+  - 10 Display Variants (5 small, 5 large)
+  - Frequency capping and analytics
 - **Products Catalog** - Centralized product information
 - **Contact Forms** - (Coming soon)
 - **Feature Requests** - (Coming soon)
@@ -23,47 +26,47 @@ yarn add shared-features
 This package requires the following peer dependencies:
 
 ```bash
-yarn add react react-dom firebase @radix-ui/themes zustand
+yarn add react react-dom firebase @radix-ui/themes zustand lucide-react
 # Optional for mobile:
 yarn add @capacitor/preferences
 ```
 
 ## Setup
 
-### 1. Initialize the package
-
-```typescript
-// src/config/shared-features.ts
-import { initSharedFeatures } from 'shared-features';
-
-export const sharedFeatures = initSharedFeatures({
-  firebaseConfig: {
-    apiKey: import.meta.env.VITE_ZAIONS_FIREBASE_API_KEY,
-    authDomain: 'aoneahsan-portfolio.firebaseapp.com',
-    projectId: 'aoneahsan-portfolio',
-  },
-  projectId: 'your-project-id',
-  projectName: 'Your Project Name',
-  platform: 'web', // or 'android', 'ios', 'extension'
-  debug: import.meta.env.DEV,
-});
-```
-
-### 2. Add environment variables
-
-Create or update your `.env` file:
+### 1. Add environment variables
 
 ```env
-# shared-features configuration
-VITE_ZAIONS_FIREBASE_API_KEY=your-api-key
+# aoneahsan.com Firebase config (get from admin)
+VITE_SHARED_FEATURES_API_KEY=
+VITE_SHARED_FEATURES_AUTH_DOMAIN=
+VITE_SHARED_FEATURES_PROJECT_ID=
+VITE_SHARED_FEATURES_STORAGE_BUCKET=
+VITE_SHARED_FEATURES_MESSAGING_SENDER_ID=
+VITE_SHARED_FEATURES_APP_ID=
 ```
 
-### 3. Initialize on app startup
+### 2. Initialize the package
 
 ```typescript
 // src/main.tsx or src/App.tsx
 import { initSharedFeatures } from 'shared-features';
-import './config/shared-features'; // Import to initialize
+
+if (import.meta.env.VITE_SHARED_FEATURES_API_KEY) {
+  initSharedFeatures({
+    firebaseConfig: {
+      apiKey: import.meta.env.VITE_SHARED_FEATURES_API_KEY,
+      authDomain: import.meta.env.VITE_SHARED_FEATURES_AUTH_DOMAIN,
+      projectId: import.meta.env.VITE_SHARED_FEATURES_PROJECT_ID,
+      storageBucket: import.meta.env.VITE_SHARED_FEATURES_STORAGE_BUCKET,
+      messagingSenderId: import.meta.env.VITE_SHARED_FEATURES_MESSAGING_SENDER_ID,
+      appId: import.meta.env.VITE_SHARED_FEATURES_APP_ID,
+    },
+    projectId: 'your-project-id',   // e.g., 'ztools', '2fa-studio'
+    projectName: 'Your Project Name', // e.g., 'ZTools', '2FA Studio'
+    platform: 'web', // or 'android', 'ios', 'extension'
+    debug: import.meta.env.DEV, // optional
+  });
+}
 ```
 
 ## Usage
@@ -175,18 +178,92 @@ interface UseCampaignsResult {
 }
 ```
 
-### `AdPanel`
+### Components
+
+#### `AdPanel`
+
+Simple single-ad panel for sidebars and footers.
+
+```tsx
+<AdPanel placement="sidebar_panel" variant="small_panel_2" className="my-ad" />
+```
+
+#### `AdSlider`
 
-Component to display a single ad.
+Small promotional slider using small panel variants.
 
 ```tsx
-<AdPanel
-  placement="sidebar_panel"
-  variant="small_panel_2"
-  className="my-ad"
+<AdSlider placement="footer_slider" className="my-slider" />
+```
+
+#### `AdBanner`
+
+Permanent promotional banner with auto-rotation and progress indicators.
+
+```tsx
+<AdBanner
+  placement="home_banner"
+  rotationInterval={10000}
+  maxCampaigns={5}
 />
 ```
 
+#### `AdModal`
+
+One-time promotional modal shown on first visit.
+
+```tsx
+import { AdModal, useOneTimeAdModal } from 'shared-features';
+
+function App() {
+  const { shouldShow, markAsShown } = useOneTimeAdModal();
+
+  return (
+    <>
+      {shouldShow && <AdModal onClose={markAsShown} />}
+      {/* Your app content */}
+    </>
+  );
+}
+```
+
+#### `AdUpdateModal`
+
+Carousel modal shown when app version changes.
+
+```tsx
+import { AdUpdateModal, useUpdateAdModal } from 'shared-features';
+
+function App() {
+  const { shouldShow, currentVersion, markAsShown } = useUpdateAdModal();
+
+  return (
+    <>
+      {shouldShow && <AdUpdateModal onClose={markAsShown} />}
+      {/* Your app content */}
+    </>
+  );
+}
+```
+
+### Modal Hooks
+
+#### `useOneTimeAdModal()`
+
+Manages one-time modal visibility (first visit).
+
+```typescript
+const { shouldShow, markAsShown } = useOneTimeAdModal();
+```
+
+#### `useUpdateAdModal(currentVersion?)`
+
+Manages update modal visibility (version change).
+
+```typescript
+const { shouldShow, previousVersion, currentVersion, markAsShown } = useUpdateAdModal();
+```
+
 ## Frequency Capping
 
 Ads automatically respect frequency capping set in the admin panel. By default, each campaign is shown to a user once every 20 days. This is tracked locally using Capacitor Preferences (mobile) or localStorage (web).